{"id":17511742,"url":"https://github.com/claws/cookiecutter-python-project","last_synced_at":"2025-10-18T01:31:06.808Z","repository":{"id":52282857,"uuid":"115694478","full_name":"claws/cookiecutter-python-project","owner":"claws","description":"A Cookiecutter template to create Python 3.6+ projects.","archived":false,"fork":false,"pushed_at":"2022-12-30T08:08:21.000Z","size":49,"stargazers_count":32,"open_issues_count":0,"forks_count":21,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T23:51:08.282Z","etag":null,"topics":["cookiecutter-template","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claws.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-29T06:33:30.000Z","updated_at":"2025-01-23T01:01:31.000Z","dependencies_parsed_at":"2023-01-31T11:01:50.043Z","dependency_job_id":null,"html_url":"https://github.com/claws/cookiecutter-python-project","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fcookiecutter-python-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fcookiecutter-python-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fcookiecutter-python-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fcookiecutter-python-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claws","download_url":"https://codeload.github.com/claws/cookiecutter-python-project/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250439113,"owners_count":21430819,"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":["cookiecutter-template","python"],"created_at":"2024-10-20T05:09:54.647Z","updated_at":"2025-10-18T01:31:06.743Z","avatar_url":"https://github.com/claws.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Cookiecutter Python Project\n###########################\n\nThis project contains a Cookiecutter template that helps you create new Python\n3.6+ package projects by automatically generating most of the boiler plate\ncontent for you.\n\nCookiecutter is a command-line utility that creates projects from templates.\nCookiecutter lets you to easily and quickly bootstrap a new project from a\ntemplate which allows you to skip all manual setup and common mistakes when\nstarting a new project.\n\nCookiecutter takes a source directory tree and copies it into your new project.\nIt replaces all the names that it finds surrounded by templating tags ``{{``\nand ``}}`` with names that it finds in the file ``cookiecutter.json``.\n\nThe Python project structure produced by this Cookiecutter template contains\nthe following items:\n\n- A minimal README.rst file.\n- A Makefile that automates many common developer tasks, such as:\n\n  - Creating a Virtual environment\n  - Checking code style.\n  - Performing static analysis checks.\n  - Running unit tests.\n  - Checking code coverage.\n  - Generating documentation.\n  - Generating, testing and uploading a project release to PyPI.\n\n- A ``setup.py`` file used to generate project install and releases.\n- A ``CONTRIBUTING.rst`` guide. On Github this file is shown when sending\n  a pull request or an issue. This file also gets included in the generated\n  developer documentation.\n- An empty ``CHANGELOG.rst`` file. This file gets included in the user\n  documentation.\n- A ``License`` file that defaults to the MIT License. Change this if\n  you choose a license other than MIT.\n- An ``examples`` directory with a minimal quickstart example script. This\n  script imports the package and prints the package version. It is also\n  called by the unit test suite to ensure it always works.\n- A ``tests`` directory containing a basic unit test (using unittest) and\n  a shell script that can be used to test a wheel distribution of the\n  package.\n- A Github Actions continuous integration configuration.\n- A ``docs`` directory with pre-configured Sphinx documentation containing:\n\n  - A minimal ``index.rst`` page\n\n  - A user focused page containing information such as installation\n    instructions, API docs, a link to the change log and instructions\n    about how to raise a bug.\n\n  - A developer focused page containing information such as contributing,\n    testing, code coverage, style compliance, type annotations and\n    documentation.\n\nIt is assumed that the new Python package will eventually be:\n\n- hosted on Github (or perhaps GitLab)\n- published to PyPI\n- linked to ReadTheDocs.\n\nThe generated docs have some references and links to those sites.\n\n\nGetting Started\n===============\n\nOne Time Setup Steps\n--------------------\n\nThe process for using Cookiecutter to create a new Python package project\nstarts with installing Cookiecutter. This is best done by creating a new\nvirtual environment specifically for cookiecutter and then installing\ncookiecutter using ``pip``. The example below shows how to do this.\n\n.. code-block:: console\n\n    $ python -m venv ccvenv --prompt cc\n    $ source ccvenv/bin/activate\n    (cc) $ pip install pip -U  # update pip to avoid any warnings\n    (cc) $ pip install cookiecutter\n\nYou are now ready to create a new Python project from the Cookiecutter\ntemplate provided by this project.\n\n\nCreate a new project\n--------------------\n\nTo create a new Python package project based on this cookiecutter template\nsimply navigate to a directory where you want to create the new project, then\nrun the ``cookiecutter`` command with a command line argument referencing this\ntemplate.\n\nThe easiest method is to reference this template via its Github URL (where 'gh'\nis a shortened form for Github):\n\n.. code-block:: console\n\n    (cc) $ cookiecutter gh:claws/cookiecutter-python-project\n\nAlternatively, if you have cloned a local copy of this template you can\nreference it directly:\n\n.. code-block:: console\n\n    (cc) $ cookiecutter path/to/cookiecutter-python-project\n\nYou will be prompted for user input to configure the project. Prompts are the\nkeys in 'cookiecutter.json' and default responses are the values. Prompts are\nshown in order.\n\nOnce you have generated your new Python package project you can exit the\ncookiecutter virtual environment as it is no longer required.\n\n.. code-block:: console\n\n    (cc) $ deactivate\n    $\n\n\nManual Modifications\n--------------------\n\nSome aspects of generating a project in a generic approach are not practical\nto completely automate so there may be a few steps remaining before you begin\nusing the new project.\n\n- If you specify a license other than MIT then you will need to update the\n  ``LICENSE`` file to contain your license content. By default it contains\n  a MIT License.\n\n- If you do not plan to publish project artifacts at GitHub, PyPI or\n  ReadTheDocs then remove any links to those sites. Affected files are:\n\n  - README.rst\n  - setup.py\n  - docs/source/index.rst\n\n- Update any additional useful classifiers in ``setup.py``. The list of\n  available classifiers can be found `here \u003chttps://pypi.python.org/pypi?:action=list_classifiers\u003e`_.\n\n\nExample\n=======\n\nBelow is an example showing exactly how to create a new Python project using\nthe template in this project. In this scenario the project is called\n``abc 123`` and the Python package is called ``abc_123``.\n\nIt is assumed that you have performed the actions outlined in the One Time\nSetup Steps section above which provides a virtual environment with\ncookiecutter installed into it.\n\nAfter running the cookiecutter command and passing it a reference to this\ntemplate the first question it asks for is the package display name. This is\nthe human friendly label that will be used in docs to refer to the project. It\nis also used to create the package name so it should not contain special\ncharacters that are invalid when used in a Python attribute. It can have spaces\nand hyphens in it. The package display name is first converted to lowercase\ntext and then any spaces or hyphens are converted to underscores to produce a\nPython package name.\n\n.. code-block:: console\n\n    (ccenv) $ cookiecutter ../cookiecutter-python-project/\n    package_display_name [Package-Name]: abc 123\n    package_name [abc_123]:\n    package_short_description [A description of the package]: This is my abc 123 package.\n    version [0.0.1]:\n    full_name [Your Name]: First Last\n    email []:\n    github_user_name [GithubUserName]: flast\n    github_repo_name [abc_123]:\n    Select license:\n    1 - MIT license\n    2 - BSD license\n    3 - Apache Software License 2.0\n    4 - GNU General Public License v3\n    5 - Not open source\n    Choose from 1, 2, 3, 4, 5 [1]:\n    year [2018]:\n\nThe project has been created in the ``abc_123`` directory.\n\n.. code-block:: console\n\n    $ cd abc_123\n\nWe can now kick the tires of this new project by performing some initial\nproject checks.\n\nFirst, let's create a project specific virtual environment and activate it.\nThis will install all of the project's development dependencies as well as\nthe project itself. The project will be installed as an editable package (by\nusing the ``-e`` flag to ``pip``).\n\n.. code-block:: console\n\n    $ make venv\n    ...\n    Enter virtual environment using:\n\n      \tsource venv/abc_123/bin/activate\n\n    $ source venv/abc_123/bin/activate\n    (abc_123) $\n\nNow that we have a virtual environment we can check the remaining convenience\nfunctions provided by the Makefile.\n\n.. code-block:: console\n\n    (abc_123) $ make style\n    (abc_123) $ make check-style\n    (abc_123) $ make check-static-analysis\n    (abc_123) $ make test\n    (abc_123) $ make test-verbose\n    (abc_123) $ make coverage\n    (abc_123) $ make check-docs\n    (abc_123) $ make docs\n    (abc_123) $ make serve-docs  # in browser navigate to http://localhost:8000/html\n    (abc_123) $ make dist\n    (abc_123) $ make dist-test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fcookiecutter-python-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaws%2Fcookiecutter-python-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fcookiecutter-python-project/lists"}