{"id":17082082,"url":"https://github.com/ebezzam/python-dev-tips","last_synced_at":"2025-04-12T20:33:09.463Z","repository":{"id":65423352,"uuid":"587669782","full_name":"ebezzam/python-dev-tips","owner":"ebezzam","description":"Minimal package to demonstrate good Python development habits","archived":false,"fork":false,"pushed_at":"2025-04-03T06:47:55.000Z","size":354,"stargazers_count":103,"open_issues_count":1,"forks_count":29,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T14:51:26.627Z","etag":null,"topics":["formatting","github-actions","packaging","profiling","python","unit-testing"],"latest_commit_sha":null,"homepage":"https://pydevtips.readthedocs.io","language":"Jupyter Notebook","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/ebezzam.png","metadata":{"files":{"readme":"README.rst","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":"2023-01-11T09:54:45.000Z","updated_at":"2025-03-20T16:19:07.000Z","dependencies_parsed_at":"2024-03-02T11:29:00.276Z","dependency_job_id":"ebea2058-773c-4d84-9867-1d9aff2a01bf","html_url":"https://github.com/ebezzam/python-dev-tips","commit_stats":{"total_commits":31,"total_committers":1,"mean_commits":31.0,"dds":0.0,"last_synced_commit":"6fb1da0d9c9dcb3800b1dbb42bf11f69a93a37e3"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebezzam%2Fpython-dev-tips","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebezzam%2Fpython-dev-tips/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebezzam%2Fpython-dev-tips/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebezzam%2Fpython-dev-tips/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ebezzam","download_url":"https://codeload.github.com/ebezzam/python-dev-tips/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248630498,"owners_count":21136451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["formatting","github-actions","packaging","profiling","python","unit-testing"],"created_at":"2024-10-14T12:59:40.734Z","updated_at":"2025-04-12T20:33:09.457Z","avatar_url":"https://github.com/ebezzam.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"***************************************\npydevtips: Python Development Tips\n***************************************\n\n.. image:: https://img.shields.io/badge/GitHub-100000?style=for-the-badge\u0026logo=github\u0026logoColor=white\n    :target: https://github.com/ebezzam/python-dev-tips\n    :alt: GitHub page\n\n.. image:: https://readthedocs.org/projects/pydevtips/badge/?version=latest\n    :target: http://pydevtips.readthedocs.io/en/latest/\n    :alt: Documentation Status\n\n.. image:: https://github.com/ebezzam/python-dev-tips/actions/workflows/poetry.yml/badge.svg\n    :target: https://github.com/ebezzam/python-dev-tips/blob/main/.github/workflows/poetry.yml\n    :alt: Unit tests and formatting\n\n.. image:: https://img.shields.io/badge/YouTube-%23FF0000.svg?style=for-the-badge\u0026logo=YouTube\u0026logoColor=white\n    :target: https://youtu.be/BmTBQicddqc?si=cnVcbo36EFNh6dg7\n    :alt: Recording\n\n.. image:: https://img.shields.io/badge/Google_Slides-yellow\n    :target: https://docs.google.com/presentation/d/1D1_JywMl2rjaeuVzpykPBOJsDIuwQKGOJB4EFZjej2s/edit#slide=id.g2eaa4b61f15_0_1346\n    :alt: Slides\n\n\n.. .. |ss| raw:: html\n\n..    \u003cstrike\u003e\n\n.. .. |se| raw:: html\n..    \u003c/strike\u003e\n\n|\n\nReproducibility is important for software: *if it's not reproducible, it's not useful*. \nEven if you don't plan on sharing your code, imagine \ncoming back to a project after a few weeks, or having\nto install it on a new machine. You'll be all the more thankful to your\npast self if you have a clear way to install and run your code.\n\nThis repository is a collection of tips and tricks for developing stable \nand reproducible Python code. There is a slight focus on scientific \ncomputing, but the general principles can apply to most Python projects.\nIf you're reading this from `GitHub \u003chttps://github.com/ebezzam/python-dev-tips\u003e`_, please check out the \n`documentation \u003chttps://pydevtips.readthedocs.io/en/latest/\u003e`_ for a\nmore in-depth explanation of the topics covered.\n\nThe intended audience is myself (as I often find myself going to past\nprojects to find how I did something!), but also for students and \nanyone who is interested in learning some new tricks or even \nsharing their own! I try to follow the principles laid out here on\ndevelopment and reproducibility, so feel free to point out any lapses\nor suggest improvements, either by opening an issue or pull request.\n\nAs is typical in open source, there are many ways to do the same thing.\nBut hopefully this gives you a starting point. Feel free to pick and \nchoose the features that you like. This flexibility is one of the best\n(and worst parts) of open source. Some of the things we cover:\n\n* Packaging and distribution with `Poetry \u003chttps://python-poetry.org/\u003e`_.\n* Virtual environments with `Conda \u003chttps://docs.conda.io/en/latest/\u003e`_ and `virtualenv \u003chttps://virtualenv.pypa.io/en/latest/\u003e`_.\n* Version control with Git/GitHub.\n* Reproducible examples with `Hydra \u003chttps://hydra.cc/\u003e`_.\n* Documentation with `Sphinx \u003chttps://www.sphinx-doc.org/en/master/\u003e`_.\n* Code formatting with Black, Flake8, and isort.\n* Unit tests and continuous integration with `pytest \u003chttps://docs.pytest.org/en/stable/\u003e`_ and `GitHub Actions \u003chttps://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python\u003e`_.\n* Remote development with `VS Code \u003chttps://code.visualstudio.com/\u003e` and `SSH \u003chttps://en.wikipedia.org/wiki/Secure_Shell\u003e`_.\n\nThe accompanying \n`slides \u003chttps://docs.google.com/presentation/d/1D1_JywMl2rjaeuVzpykPBOJsDIuwQKGOJB4EFZjej2s/edit#slide=id.g2eaa4b61f15_0_1346\u003e`__ \nand `video \u003chttps://youtu.be/okxaTuBdDuY?si=5AQ5pOpmsCH8BLt2\u0026t=3803\u003e`__\nare from a tutorial given at LauzHack's `Deep Learning Bootcamp \u003chttps://github.com/LauzHack/deep-learning-bootcamp\u003e`__. \nFeel free to modify and use it for your own purposes.\n\n.. note::\n\n    A good amount of this documentation and code is written with `GitHub \n    Copilot \u003chttps://github.com/features/copilot\u003e`_, which I highly recommend for development. If you don't like\n    writing documentation, it is a great way to get started as it is able to \n    understand the functionality of your code and produce meaningful text to describe it. \n    It should be used be used with caution, *but it can be a great tool for getting started*\n    and you often you need to make a few tweaks (*like the previous repetition*).\n    But it's a huge time-saver!\n\nInstallation\n============\n\nThis \"dummy\" package can be installed with pip:\n\n.. code:: bash\n\n    pip install pydevtips\n\nOr from source. Firstly, Poetry must be installed: https://python-poetry.org/docs/#installation \n\n.. code:: bash\n\n    # -- recommend using pipx\n    pipx install poetry\n\n    # -- or with official installer\n    # curl -sSL https://install.python-poetry.org | python3 -\n\n    # I recommend creating virtual environment in the project folder\n    poetry config virtualenvs.in-project true\n\n\nThen the following commands can be run:\n\n.. code:: bash\n\n    # get source code\n    git clone git@github.com:ebezzam/python-dev-tips.git\n    cd python-dev-tips\n\n    # create new environment, press enter to accept\n    # -- important to set python version, otherwise `python` executable may not exist \n    # -- (would be `python3` instead)\n    conda create -n project_env python=3.11\n\n    # view available environments\n    conda info --envs\n\n    # activate environment\n    conda activate project_env\n\n    # install package locally\n    (project_env) poetry install --with dev\n\n    # install pre-commit hooks\n    (project_env) pre-commit install\n\n    # run tests\n    (project_env) pytest\n\n    # deactivate environment\n    (project_env) conda deactivate\n\nOr without ``conda`` and just Poetry:\n\n.. code:: bash\n\n    # get source code\n    git clone git@github.com:ebezzam/python-dev-tips.git\n    cd python-dev-tips\n\n    # install package locally\n    poetry install --with dev\n    # -- `poetry env info` to see where the virtual environment is located\n\n    # install pre-commit hooks\n    poetry run pre-commit install\n\n    # run tests\n    poetry run pytest\n\n    ## NOTE that Python related commands need to be run \n    ## with `poetry run` or by activating the virtual environment\n    ## https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment\n\nExamples\n========\n\nExamples can be found in the ``examples`` and ``notebooks`` folders.\nScripts from the ``examples`` folder should be run from the root of the\nrepository, e.g.:\n\n.. code:: bash\n\n    python examples/real_convolve.py\n\nParameter setting is done with `hydra \u003chttps://hydra.cc/\u003e`_. More on that\nin the `Reproducible examples \u003chttps://pydevtips.readthedocs.io/en/latest/reproducible.html\u003e`_\nsection of the documentation.\n\n\nTODO\n====\n\n- switch to ruff for code formatting: https://docs.astral.sh/ruff/\n- numba: https://numba.pydata.org/\n- picking a license\n- change documentation links to main branch\n- github page\n- point out features in scripts: object-oriented, asserts, tqdm, type hints\n- manifest file to not include file in package\n- GitHub actions for releasing to PyPi when changes to version\n- pytorch compatible\n- Cython / C++\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febezzam%2Fpython-dev-tips","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febezzam%2Fpython-dev-tips","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febezzam%2Fpython-dev-tips/lists"}