{"id":38506228,"url":"https://github.com/angelakdang/simple-python-template","last_synced_at":"2026-01-17T06:12:29.074Z","repository":{"id":227324228,"uuid":"771060710","full_name":"angelakdang/simple-python-template","owner":"angelakdang","description":"The Python project template I wish I had when I was an engineer learning how to code.","archived":false,"fork":false,"pushed_at":"2024-03-13T15:28:16.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-03-13T19:00:43.499Z","etag":null,"topics":["project-template","python","python-for-engineers","python-template","template"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/angelakdang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-12T16:08:30.000Z","updated_at":"2024-03-12T18:01:19.000Z","dependencies_parsed_at":"2024-03-12T19:09:22.891Z","dependency_job_id":null,"html_url":"https://github.com/angelakdang/simple-python-template","commit_stats":null,"previous_names":["angelakdang/simple-python-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/angelakdang/simple-python-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angelakdang%2Fsimple-python-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angelakdang%2Fsimple-python-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angelakdang%2Fsimple-python-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angelakdang%2Fsimple-python-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angelakdang","download_url":"https://codeload.github.com/angelakdang/simple-python-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angelakdang%2Fsimple-python-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28502012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["project-template","python","python-for-engineers","python-template","template"],"created_at":"2026-01-17T06:12:27.890Z","updated_at":"2026-01-17T06:12:29.066Z","avatar_url":"https://github.com/angelakdang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nThis is the Python project template I wish I had when I was learning how to code in Python. \nAs an engineer, I knew what I wanted my code to do, but I didn't know what packages I was installing,\nwhere they were being installed, and things got messy quickly.\n\nThis is a template for creating a robust Python project using some basic software engineering principles, where \nthe code is version controlled, linted (style checked), and developed within a virtual environment so that it is \nreproducible, no matter who is running your code or where your code is running. These are the principles that I found \nwould have found useful early on in my Python developer journey.\n\n## About the tools\n\n### Git\n\nGit is a tool that manages and tracks changes to your files, making collaboration and version control easier. It keeps a\nrecord of every change you make to your documents, just like taking snapshots. This means you can easily go back in time\nand see the previous versions of your work. If you make a mistake or want to compare different versions, Git has got\nyour back.\n\nGit is especially handy when you're working on projects with others. It allows multiple people to work on the same\nfiles simultaneously without stepping on each other's toes. Git handles the merging of changes and resolves conflicts,\nmaking sure everyone's contributions fit together seamlessly.\n\nImagine you're working on a group project or writing a research paper. With Git, you can create a repository that holds\nall the project files. Each time you make a change, Git saves it along with a message explaining what you did. This\ncreates a timeline of your progress and makes it easy to track who made which changes.\n\nAdditionally, Git enables collaboration beyond the boundaries of your own group. You can share your repository with\nothers, allowing them to view your work, make their own changes, and suggest improvements. Git keeps everything\norganized and ensures that changes are properly tracked and attributed.\n\n### pyenv\n\nIt is possible to have multiple versions of Python installed at the same time. This is normally needed to run certain\npackages or executables that are built using a specific version. Pyenv helps manage the installation and multiple\nversions of Python.\n\n\u003e [!WARNING]\n\u003e **pyenv + Poetry DOES NOT play well with conda.**\n\u003e If you have previously installed Python and/or Anaconda/Miniforge/Miniconda/etc. UNINSTALL IT. The \"pyenv + Poetry\"\n\u003e setup does not play well with conda, nor is conda necessary. Poetry does more than conda and in a more user-friendly \n\u003e manner (in my opinion).\n\n\u003e [!NOTE]\n\u003e If you installed Python from [python.org](https://www.python.org/downloads/) you'll likely only have one version\n\u003e (e.g. 3.11.2) available. This is fine to start, but if you end up working on other (older) projects that requires a \n\u003e different version of Python, you'll need to install those.\n\nYou can use pyenv to install whatever versions of Python you would like (generally the \n[latest version](https://www.python.org/downloads/)).\nYou can use pyenv to install any additional version of Python you need by running `pyenv install \u003cversion\u003e`. We\nrecommend a version each of 3.8, 3.9, 3.10, and 3.11. A good place to start is looking at the projects you might be\ncontributing to and downloading the version required for that.\n\n### Poetry\n\nEvery Python project should lock its dependent libraries (packages) to specific versions and follow [semantic\nversioning](https://semver.org/). Using a virtual environment allows you to create an isolated Python environment for\nyor project where you can pin down your dependencies (packages), avoid version conflicts, and create fully\nreproducible builds. To learn more about virtual environments, you can read\n[this article](https://realpython.com/python-virtual-environments-a-primer/). \nMy preferred tool is [Poetry](https://python-poetry.org/docs/).\n\n## Getting Started\n\n### Using this template\n\nClick `Use this template` to create a new repository based on this one.\n\n### Instantiate virtual environment\nInstantiate your virtual environment within the project folder by running:\n`poetry install`.\n\nActivate your virtual environment by running `poetry shell`.\n\n#### Poetry configuration\n\nA project will typically have three files that pertain to configuring the Poetry installation:\n\n* `poetry.toml`: Defines the local [configuration](https://python-poetry.org/docs/configuration/) of Poetry. It is a \n  best practice to create the virtual environment in the project's root directory. This limits confusion as to which \n  virtual environment is used for which project\n* `pyproject.toml`: Defines the Poetry project (your Python project), including metadata about your project and its \n  dependencies (required packages)\n* `poetry.lock`: This won't be shown here, but once you've dones a `poetry install` on a new project, a `poetry.\n  lock` file will be created. This locks the specific versions that you use during the development of your project. \n  This ensures reproducibility. When you're working off of an exisiting Poetry project, you'll run `poetry install \n  --sync` to honor all the \"locked in\" versions of the packages used in the project.\n\n### Install pre-commit\n\nPre-commit is a way to identify simple issues before submission to code review. \nWe run pre-commit hooks (checks) on every commit to automatically point out issues in code such as missing semicolons, \ntrailing whitespace, and debug statements. By pointing these issues out before code review, this allows a code \nreviewer (or anyone else looking at our code) to focus on the architecture of a change while not wasting time with \ntrivial style nitpicks.\n\nEnsure the pre-commit hooks are installed by running (in your virtual environment): `pre-commit install`\n\nThen run `pre-commit run --all-files`.\n\n### Create a Jupyter notebook kernel\n\nTo use Jupyter Notebook during your development, you can create a kernel that reflects the Poetry\nenvironment by running `ipython kernel install --name pipeline_water_wells --user`. Then you can run `jupyter notebook`\nfrom your active shell and set the correct kernel in both new and existing notebooks.\n\n### Add `.env` file for secrets\n\nSometimes, to connect to data sources, you'll need to specify some usernames and passwords to access the various\ndatabases. This information should be kept in a `.env` file and NEVER shared or committed to a public repository.\n\nCreate a `.env` file in the root directory to store API keys, passwords, connection string, etc.:\n\n```bash\nSUPER_SECRET_PASSWORD='super-secret-password'\n```\n\n## Project structure\n\nThe goal is to be able to execute your code by running `poetry run python src/main.py`. You can run this\ncommand in the terminal to check if you have set up the project correctly (including the `.env` file). The output\nshould look something like below:\n\n![Output of main.py](img/run-main.png)\n\nIdeally, you will create all of your code within the main() function, as shown in the `main.py` file. If your\nsupporting functions are long, you can keep those in a separate Python file to improve readability.\n\n### Tests\n\nIn software engineering, it is important to test code to ensure that it works as expected. This can be done by\nwriting a function that tests the code and applying it to a small table to verify that it works correctly. By doing\nthis, you can be confident that the function works properly and any errors are happening elsewhere in the code.\n\nTests are located in the subfolder `tests/`\n\n## Pandas vs Polars\n\nPandas is a very popular package that allows users to structure data in tables, aka DataFrames (like a what you might\nsee in a spreadsheet) and manipulate it. Polars is a high-performing DataFrame library similar to Pandas but\nperforms much faster for most data manipulation. Polars is a good choice if your DataFrames are very large (\u003e 1MM rows).\n\n## References \u0026 Additional Resources\n\n- [Test Driven Development](https://medium.com/@patrick.tolosa/tdd-for-dummies-step-by-step-6fa828af21d0)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangelakdang%2Fsimple-python-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangelakdang%2Fsimple-python-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangelakdang%2Fsimple-python-template/lists"}