{"id":24818604,"url":"https://github.com/kempnerinstitute/python-package-template","last_synced_at":"2025-09-07T16:46:30.036Z","repository":{"id":251428648,"uuid":"834314250","full_name":"KempnerInstitute/python-package-template","owner":"KempnerInstitute","description":"A step by step guidelines to start a new python package or convert current codebase into a package.","archived":false,"fork":false,"pushed_at":"2024-07-26T23:39:39.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T19:43:36.274Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/KempnerInstitute.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,"publiccode":null,"codemeta":null}},"created_at":"2024-07-26T23:19:30.000Z","updated_at":"2024-08-02T20:28:59.000Z","dependencies_parsed_at":"2024-08-03T00:07:44.787Z","dependency_job_id":null,"html_url":"https://github.com/KempnerInstitute/python-package-template","commit_stats":null,"previous_names":["kempnerinstitute/python-package-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KempnerInstitute/python-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KempnerInstitute%2Fpython-package-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KempnerInstitute%2Fpython-package-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KempnerInstitute%2Fpython-package-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KempnerInstitute%2Fpython-package-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KempnerInstitute","download_url":"https://codeload.github.com/KempnerInstitute/python-package-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KempnerInstitute%2Fpython-package-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274065504,"owners_count":25216443,"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","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-01-30T17:09:06.154Z","updated_at":"2025-09-07T16:46:30.014Z","avatar_url":"https://github.com/KempnerInstitute.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Packaging User Guide and Template\n\nThis is a guide to packaging and distributing Python code. [PYPA (Python Packaging Authority)](https://www.pypa.io/en/latest/) is a working group that maintains a core set of software projects used in Python packaging. The PYPA publishes the [Python Packaging User Guide](https://packaging.python.org/en/latest/), which is the official guide to packaging Python code. \n\n\n## Starting a new project\n\nThe following are the basic steps to start a new Python project:\n\n1. Create the project directory structure\n\n  - Set up your project directory following the [flat structure](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/) convention. \n\n\n    ```bash\n    my_package/\n    ├── my_package/\n    │   ├── __init__.py\n    │   └── module.py\n    ├── tests/\n    |   ├── __init__.py\n    │   └── test_module.py\n    ├── LICENSE\n    ├── README.md\n    └── pyproject.toml\n    ```\n2. Intialize a Git repository\n\n    ```bash\n    cd my_package\n    git init\n    ```\n3. Create `pyproject.toml` file\n\n  - Define the metadata for your project in the pyproject.toml file. The file contains three sections: `build-system`, `project`, and `tool`. The `build-system` section specifies the build backend and the required build dependencies.The `project` section specifies the project metadata. The `tool` section specifies the build tool to use. The first two sections are required, and the last section is optional. \n\n  - The following file shows an example of a `pyproject.toml` file: \n\n    ```toml\n    [build-system]\n    requires = [\"setuptools\", \"wheel\"]\n    build-backend = \"setuptools.build_meta\"\n\n    [project]\n    name = \"my_package\"\n    version = \"0.1.0\"\n    description = \"A sample Python package\"\n    authors = [\n    { name = \"Your Name\", email = \"your.email@example.com\" }\n    ]\n    license = { file = \"LICENSE\" }\n    classifiers = [\n    \"Programming Language :: Python :: 3\",\n    \"License :: OSI Approved :: MIT License\",\n    \"Operating System :: OS Independent\"\n    ]\n    dependencies = []\n\n    ```\n\n  - Note that you can also use `setup.py` file to define the metadata for your project. However, the `pyproject.toml` file is the recommended way to define the metadata for your project. In case of adding C extensions, you can use `setup.py` file.\n\n4. Add License file\n\n  - Add a license file to your project. The license file should contain the license text. You can use the [MIT License](https://opensource.org/licenses/MIT) as a template for your license file.\n  - Visit [Choose a License](https://choosealicense.com/) to select an appropriate license for your project.\n\n5. Add README file\n\n- Add a README file to your project. The README file should contain the project description, installation instructions, usage instructions, and other relevant information about the project. \n\n6. Add `__init__.py` file\n\n- Add an `__init__.py` file to the package directory. Please see the folder structure at step 1. The `__init__.py` file can be empty or contain initialization code for the package.\n\n7. Add a module file\n\n- Add a module file to the package directory. The module file contains the code for your package. You can add multiple module files to the package directory.\n\n8. Add a test file\n\n- Add a test file to the tests directory. The test file contains the test code for your package. There are two types of tests: unit tests and integration tests. You can use the `unittest` module or the `pytest` library to write tests for your package.\n- It is a good practice to write tests while developing your package. Writing tests helps you to ensure that your package works as expected and to catch bugs early in the  process.\n\n9. Add a `.gitignore` file\n\n- Add a `.gitignore` file to your project. The `.gitignore` file specifies the files and directories that should be ignored by Git. \n\n10. Install your package in editable mode\n\n- Install your package in editable mode using the following command:\n\n  ```bash\n  pip install -e .\n  ```\n\nPlease see the [Python Packaging Template](python_packaging_template) for a template that you can use to start a new Python project. \n\n## Converting an existing project to a package\n\n1. Organize the Directory Structure\n\n  - Ensure your current project follows the standard flat directory structure as shown above.\n  - Make sure that all files are saved and pushed to the repository, if applicable.\n\n2. Add pyproject.toml\n\n  - Create and configure the pyproject.toml file with appropriate metadata.\n\n3. Add License and Readme Files\n\n  - Ensure your project includes a LICENSE file and a README.md file.\n\n4. Move Source Code into Package Directory\n\n  - Refactor your code into the my_package directory to align with best practices.\n\n5. Write or Update Tests\n\n  - Create or update test scripts in the tests directory.\n\n6. Install and Test Your Package\n\n  - Install your package locally and run tests to verify everything works correctly.\n\n7. Version Control\n\n  - Initialize or update your Git repository with the refactored project structure.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkempnerinstitute%2Fpython-package-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkempnerinstitute%2Fpython-package-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkempnerinstitute%2Fpython-package-template/lists"}