diff --git a/docs/conda.rst b/docs/conda.rst deleted file mode 100644 index 4d73bbc60..000000000 --- a/docs/conda.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. _conda-packages: - -================================= -Distributing Packages via `conda` -================================= - -conda_ is an open-source package manager very popular in the Python -ecosystem that can be used as an alternative to pip_. It is especially helpful -when distributing packages that rely on compiled libraries (e.g. when you need -to use some C code to achieve performance improvements) and uses Anaconda_ as -its standard repository (the PyPI_ equivalent in the conda_ world). - -The process of creating conda_ packages consists basically in creating some extra -files that describe general recipe to build your project in different operating systems. -These recipe files can in theory coexist within the same repository as generated -by PyScaffold. - -While this approach is completely fine and works well, a package -uploaded by a regular user to Anaconda_ will not be available if someone simply try to -install it via ``conda install ``. -This happens because Anaconda_ and conda_ are organised in terms of `channels`_ and regular -users cannot upload packages to the default channel. -Instead, separated personal channels need to be used for the upload and explicitly -selected with the ``-c `` option in ``conda install``. - -It is important however to consider that mixing many channels together might -create clashes in dependencies (although conda_ tries very hard to avoid clashes by -using channel preference ordering and a clever resolution algorithm). - -A general practice that emerged in the conda_ ecosystem is to organise packages -in large communities that share a single and open repository in Anaconda_, that -rely on specific procedures and heavy continuous integration for publishing -cohesive packages. These procedures, however, might involve creating a second -repository (separated from the main code base) to just host the recipe files. -For that reason, PyScaffold does not currently generate conda_ recipe files -when creating new projects. - -Instead, if you are an open-source developer and are interested in distributing -packages via conda_, our recommendation is to try `publishing your package on conda-forge`_ -(unless you want to target a specific community such as bioconda_). -conda-forge_ is one of the largest channels in Anaconda_ and works as the -central hub for the Python developers in the conda_ ecosystem. - -Once you have your package published to PyPI_ using the project generated by PyScaffold, -you can create a *conda-forge feedstock* [#conda1]_ using a special tool called grayskull_ and -following the instructions_. -Please make sure to check PyScaffold community tips in :discussion:`422`. - -If you still need to use a personal custom channel in Anaconda_, please -checkout `conda-build tutorials`_ for further information. - -.. tip:: - It is not strictly necessary to publish your package to Anaconda_ for your - users to be able to install it if they are using conda_ -- - ``pip install`` can still be used from a `conda environment`_. - However, if you have dependencies that are also published in Anaconda_ and - are not pure Python projects (e.g. ``numpy`` or ``matplotlib``), or that - rely on `virtual environments`_, it is generally advisable to do so. - - -.. [#conda1] **feedstock** is the term used by conda-forge_ for the companion - repository with recipe files - - -.. _pip: https://pip.pypa.io/ -.. _PyPI: https://pypi.org/ -.. _conda: https://conda.io -.. _Anaconda: https://anaconda.org -.. _channels: https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html -.. _custom channels: https://conda.io/projects/conda/en/latest/user-guide/tasks/create-custom-channels.html -.. _conda-forge: https://conda-forge.org -.. _bioconda: https://bioconda.github.io -.. _publishing your package on conda-forge: https://conda-forge.org/docs/maintainer/adding_pkgs.html -.. _grayskull: https://pypi.org/project/grayskull/ -.. _instructions: https://conda-forge.org/docs/maintainer/adding_pkgs.html#step-by-step-instructions -.. _conda-build tutorials: https://docs.conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html -.. _conda environment: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment -.. _virtual environments: https://realpython.com/python-virtual-environments-a-primer/ diff --git a/docs/configuration.rst b/docs/configuration.rst deleted file mode 100644 index 2f100c8ad..000000000 --- a/docs/configuration.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. _configuration: - -============= -Configuration -============= - -Package Configuration -===================== - -Projects set up with PyScaffold rely on `setuptools`_, and therefore can be -easily configured/customised via ``setup.cfg``. Check out the example below: - -.. literalinclude:: ./example_setup.cfg - :language: ini - -You might also want to have a look on `pyproject.toml`_ for specifying -dependencies required during the build: - -.. literalinclude:: ../src/pyscaffold/templates/pyproject_toml.template - :language: toml - -Please note PyScaffold will add some internal information to ``setup.cfg``, -we do that to make updates a little smarter. - -.. note:: - To avoid splitting the configuration and build parameters among several - files, PyScaffold uses the same file as `setuptools`_ (``setup.cfg``). - Storing configuration in `pyproject.toml`_ is not supported. - In the future, if the default build metadata location changes (as proposed - by `PEP 621`_), PyScaffold will follow the same pattern. - - -.. _default-cfg: - -PyScaffold's Own Configuration -============================== - -PyScaffold also allows you to save your favourite configuration to a file that -will be automatically read every time you run ``putup``, this way you can avoid -always retyping the same command line options. - -The locations of the configuration files vary slightly across platforms, but in -general the following rule applies: - -- Linux: ``$XDG_CONFIG_HOME/pyscaffold/default.cfg`` with fallback to ``~/.config/pyscaffold/default.cfg`` -- OSX: ``~/Library/Preferences/pyscaffold/default.cfg`` -- Windows(≥7): ``%APPDATA%\pyscaffold\pyscaffold\default.cfg`` - -The file format resembles the ``setup.cfg`` generated automatically by -PyScaffold, but with only the ``metadata`` and ``pyscaffold`` sections, for -example: - -.. code-block:: ini - - [metadata] - author = John Doe - author-email = john.joe@gmail.com - license = MPL-2.0 - - [pyscaffold] - extensions = - cirrus - pre-commit - -With this file in place, typing only:: - - $ putup myproj - -will have the same effect as if you had typed:: - - $ putup --license MPL-2.0 --cirrus --pre-commit myproj - -.. note:: - - For the time being, only the following options are allowed in the config file: - - - **metadata** section: ``author``, ``author-email`` and ``license`` - - **pyscaffold** section: ``extensions`` (and associated opts) - - Options associated with extensions are the ones prefixed by an extension name. - - -To prevent PyScaffold from reading an existing config file, you can pass the -``--no-config`` option in the CLI. You can also save the given options when -creating a new project with the ``--save-config`` option. Finally, to read the -configurations from a location other then the default, use the ``--config PATH`` -option. See ``putup --help`` for more details. - -.. warning:: - - *Experimental Feature* - We are still evaluating how this new and exciting - feature will work, so its API (including file format and name) is not considered - stable and might change between minor versions. As previously stated, if - the configuration file for `setuptools`_ changes (e.g. with `PEP 621`_), - PyScaffold will follow that and change its own configuration. - - This means that in future versions, PyScaffold will likely adopt a more - `pyproject.toml`-style configuration (and as a consequence the file name - and extension might change). - - -.. _setuptools: https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html -.. _pyproject.toml: https://setuptools.readthedocs.io/en/latest/build_meta.html -.. _PEP 621: https://www.python.org/dev/peps/pep-0621/ diff --git a/docs/examples.rst b/docs/examples.rst deleted file mode 100644 index 3688a3bf8..000000000 --- a/docs/examples.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _examples: - -======== -Examples -======== - -Just a few examples to get you an idea of how easy PyScaffold is to use: - -``putup my_little_project`` - The simplest way of using PyScaffold. A directory ``my_little_project`` is - created with a Python package named exactly the same. The MIT license will be used. - -``putup -i my_little_project`` - If you are unsure on how to use PyScaffold, or keep typing ``putup --help`` - all the time, the **experimental** ``--interactive`` (or simply ``-i``), is - your best friend. - It will open your default text editor with a file containing examples and - explanations on how to use ``putup`` (think of it as an "editable" ``--help`` - text, once the file is saved and closed all the values you leave there are - processed by PyScaffold). You might find some familiarities in the way this - option works with ``git rebase -i``, including the capacity of choosing a - different text editor by setting the ``EDITOR`` (or ``VISUAL``) environment - variable in your terminal. - -``putup skynet -l GPL-3.0-only -d "Finally, the ultimate AI!" -u http://sky.net`` - This will create a project and package named *skynet* licensed under the GPL3. - The *description* inside ``setup.cfg`` is directly set to "Finally, the ultimate AI!" - and the homepage to http://sky.net. - -``putup Scikit-Gravity -p skgravity -l BSD-3-Clause`` - This will create a project named *Scikit-Gravity* but the package will be - named *skgravity* with license new-BSD [#ex1]_. - -``putup youtub --django --pre-commit -d "Ultimate video site for hot tub fans"`` - This will create a web project and package named *youtub* that also includes - the files created by `Django's `_ - ``django-admin`` [#ex2]_. The *description* in ``setup.cfg`` will be set and - a file ``.pre-commit-config.yaml`` is created with a default setup for - `pre-commit `_. - -``putup thoroughly_tested --cirrus`` - This will create a project and package *thoroughly_tested* with files ``tox.ini`` - and ``.cirrus.yml`` for `Tox `_ and - `Cirrus CI `_. - -``putup my_zope_subpackage --name my-zope-subpackage --namespace zope --package subpackage`` - This will create a project under the ``my_zope_subpackage`` directory with - the *installation name* of ``my-zope-subpackage`` (this is the name used by - pip_ and PyPI_), but with the following corresponding import statement:: - - from zope import subpackage - # zope is the namespace and subpackage is the package name - - To be honest, there is really only the `Zope project `_ - that comes to my mind which is using this exotic feature of Python's packaging system. - Chances are high, that you will never ever need a namespace package in your life. - To learn more about namespaces in the Python ecosystem, check `PEP 420`_. - - -.. [#ex1] Notice the usage of `SPDX identifiers`_ for specifying the license - in the CLI - -.. [#ex2] Requires the installation of pyscaffoldext-django_. - - -.. _SPDX identifiers: https://spdx.org/licenses/ -.. _pyscaffoldext-django: https://pyscaffold.org/projects/django -.. _pip: https://pip.pypa.io -.. _PyPI: https://pypi.org -.. _PEP 420: https://www.python.org/dev/peps/pep-0420/ diff --git a/docs/faq.rst b/docs/faq.rst index f164d1b43..824deb771 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -298,6 +298,83 @@ Using some CI service, why is the version `unknown` or `my_project-0.0.post0.dev i.e. ``git fetch origin --tags``. +.. _conda-packages: + +Creating and distributing `conda` packages +------------------------------------------ + +conda_ is an open-source package manager very popular in the Python +ecosystem that can be used as an alternative to pip_. It is especially helpful +when distributing packages that rely on compiled libraries (e.g. when you need +to use some C code to achieve performance improvements) and uses Anaconda_ as +its standard repository (the PyPI_ equivalent in the conda_ world). + +The process of creating conda_ packages consists basically in creating some extra +files that describe general recipe to build your project in different operating systems. +These recipe files can in theory coexist within the same repository as generated +by PyScaffold. + +While this approach is completely fine and works well, a package +uploaded by a regular user to Anaconda_ will not be available if someone simply try to +install it via ``conda install ``. +This happens because Anaconda_ and conda_ are organised in terms of `channels`_ and regular +users cannot upload packages to the default channel. +Instead, separated personal channels need to be used for the upload and explicitly +selected with the ``-c `` option in ``conda install``. + +It is important however to consider that mixing many channels together might +create clashes in dependencies (although conda_ tries very hard to avoid clashes by +using channel preference ordering and a clever resolution algorithm). + +A general practice that emerged in the conda_ ecosystem is to organise packages +in large communities that share a single and open repository in Anaconda_, that +rely on specific procedures and heavy continuous integration for publishing +cohesive packages. These procedures, however, might involve creating a second +repository (separated from the main code base) to just host the recipe files. +For that reason, PyScaffold does not currently generate conda_ recipe files +when creating new projects. + +Instead, if you are an open-source developer and are interested in distributing +packages via conda_, our recommendation is to try `publishing your package on conda-forge`_ +(unless you want to target a specific community such as bioconda_). +conda-forge_ is one of the largest channels in Anaconda_ and works as the +central hub for the Python developers in the conda_ ecosystem. + +Once you have your package published to PyPI_ using the project generated by PyScaffold, +you can create a *conda-forge feedstock* [#conda1]_ using a special tool called grayskull_ and +following the instructions_. +Please make sure to check PyScaffold community tips in :discussion:`422`. + +If you still need to use a personal custom channel in Anaconda_, please +checkout `conda-build tutorials`_ for further information. + +.. tip:: + It is not strictly necessary to publish your package to Anaconda_ for your + users to be able to install it if they are using conda_ -- + ``pip install`` can still be used from a `conda environment`_. + However, if you have dependencies that are also published in Anaconda_ and + are not pure Python projects (e.g. ``numpy`` or ``matplotlib``), or that + rely on `virtual environments`_, it is generally advisable to do so. + + +.. [#conda1] **feedstock** is the term used by conda-forge_ for the companion + repository with recipe files + + +.. _pip: https://pip.pypa.io/ +.. _PyPI: https://pypi.org/ +.. _conda: https://conda.io +.. _Anaconda: https://anaconda.org +.. _channels: https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html +.. _custom channels: https://conda.io/projects/conda/en/latest/user-guide/tasks/create-custom-channels.html +.. _conda-forge: https://conda-forge.org +.. _bioconda: https://bioconda.github.io +.. _publishing your package on conda-forge: https://conda-forge.org/docs/maintainer/adding_pkgs.html +.. _grayskull: https://pypi.org/project/grayskull/ +.. _instructions: https://conda-forge.org/docs/maintainer/adding_pkgs.html#step-by-step-instructions +.. _conda-build tutorials: https://docs.conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html +.. _conda environment: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment +.. _virtual environments: https://realpython.com/python-virtual-environments-a-primer/ .. _blog post by Ionel: https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure .. _src layout: https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure .. _discussions: https://github.com/pyscaffold/pyscaffold/discussions @@ -325,7 +402,6 @@ Using some CI service, why is the version `unknown` or `my_project-0.0.post0.dev .. _pyscaffoldext-dsproject: https://github.com/pyscaffold/pyscaffoldext-dsproject .. _Semantic Versioning: https://semver.org/ .. _dependency hell: https://en.wikipedia.org/wiki/Dependency_hell -.. _PyPI: https://pypi.org/ .. _devpi: https://devpi.net/ .. _Nexus: https://www.sonatype.com/product-nexus-repository .. _packaging, versioning and continuous integration: https://florianwilhelm.info/2018/01/ds_in_prod_packaging_ci/ diff --git a/docs/index.rst b/docs/index.rst index c2c7dc263..511a5ea8e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,56 +14,6 @@ practices of the Python ecosystem, helping you and your team to stay sane, happy and productive. The best part? It is stable and has been used by thousands of developers for over half a decade! -.. _quickstart: - -A single command is all you need to quickly start coding like a Python rockstar, -skipping all the difficult and tedious bits:: - - putup my_project - -This will create a new folder called ``my_project`` containing a -*perfect project template* with everything you need for getting things done. -Checkout out `this demo project`_, which was set up using Pyscaffold. - -.. tip:: - .. versionadded:: 4.0 - We are trying out a brand new *interactive mode* that makes it - even easier to use PyScaffold in its full potential. - If you want to give it a shot, use the ``--interactive``, or simply ``-i`` option. - - The interactive command equivalent to the previous example is: - ``putup -i my_project``. - -You can ``cd`` into your new project and interact with it from the -command line after creating (or activating) an `isolated -development environment`_ (with virtualenv_, conda_ or your preferred tool), -and performing the usual editable_ install:: - - pip install -e . - -… all set and ready to go! Try the following in a Python shell: - -.. code-block:: pycon - - >>> from my_project.skeleton import fib - >>> fib(10) - 55 - -Or if you are concerned about performing package maintainer tasks, make sure to -have tox_ installed and see what we have prepared for you out of the box:: - - tox -e docs # to build your documentation - tox -e build # to build your package distribution - tox -e publish # to test your project uploads correctly in test.pypi.org - tox -e publish -- --repository pypi # to release your package to PyPI - tox -av # to list all the tasks available - -Type ``putup -h`` to learn about :ref:`other things PyScaffold can do ` for your project, -and if you are not convinced yet, have a look on these :ref:`reasons to use PyScaffold `. - -There is also a `video tutorial`_ on how to develop a command-line application with the help of PyScaffold. - - .. note:: This document refers to the latest version of PyScaffold (v4). Please refer to `v3.3`_ for the previous stable version. @@ -82,46 +32,19 @@ Contents Why PyScaffold? Features Installation - Examples - Configuration + Usage & Examples Dependency Management Migrating to PyScaffold Updating your Project's Scaffold Extending PyScaffold - Creating Conda Packages - Contributions & Help FAQ - License + Contributions & Help Contributors Changelog + License Module Reference -Notes ------ - -#. PyScaffold's project template makes use of a dedicated ``src`` - folder to store all the package files meant for distribution (additional - files like tests and documentation are kept in their own separated folders). - You can find some comments and useful links about this design decision in - our :ref:`FAQ `. - -#. The ``pip install -e .`` command installs your project in editable_ mode, - making it available in import statements as any other Python module. - It might fail if your have an old version of Python's package manager and - tooling in your current environment. Please make sure you are using the - intended environment (either a `virtual environment`_ [*recommended*] or the - default installation of Python in the operating system) and try to update - them with ``python -m pip install -U pip setuptools``. - -#. If you are using a `virtual environment`_, please remember to - re-activate it everytime you close your shell, otherwise you will not be - able to import your project in the REPL_. To check if you have already - activated it you can run ``which python`` on Linux and OSX, ``where python`` - on the classical Windows command prompt, or ``Get-Command python`` on - PowerShell. - - Indices and tables ------------------ @@ -132,14 +55,4 @@ Indices and tables .. _PyPI: https://pypi.org/ .. _pip: https://pip.pypa.io/ -.. _video tutorial: https://www.youtube.com/watch?v=JwwlRkLKj7o -.. _this demo project: https://github.com/pyscaffold/pyscaffold-demo -.. _editable: https://pip.pypa.io/en/stable/reference/pip_install/#install-editable -.. _isolated development environment: https://realpython.com/python-virtual-environments-a-primer/ -.. also good, but sometimes medium can get on the way: https://towardsdatascience.com/virtual-environments-104c62d48c54 -.. _virtualenv: https://virtualenv.pypa.io -.. _conda: https://conda.io -.. _REPL: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop -.. _virtual environment: https://realpython.com/python-virtual-environments-a-primer/ -.. _tox: https://tox.readthedocs.org/ .. _v3.3: https://pyscaffold.org/en/v3.3.x/ diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 000000000..920eb54cd --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,260 @@ +.. _examples: + +================ +Usage & Examples +================ + +.. _quickstart: + +Quickstart +========== + +A single command is all you need to quickly start coding like a Python rockstar, +skipping all the difficult and tedious bits:: + + putup my_project + +This will create a new folder called ``my_project`` containing a +*perfect project template* with everything you need for getting things done. +Checkout out `this demo project`_, which was set up using Pyscaffold. + +.. tip:: + .. versionadded:: 4.0 + We are trying out a brand new *interactive mode* that makes it + even easier to use PyScaffold in its full potential. + If you want to give it a shot, use the ``--interactive``, or simply ``-i`` option. + + The interactive command equivalent to the previous example is: + ``putup -i my_project``. + +You can ``cd`` into your new project and interact with it from the +command line after creating (or activating) an `isolated +development environment`_ (with virtualenv_, conda_ or your preferred tool), +and performing the usual editable_ install:: + + pip install -e . + +… all set and ready to go! Try the following in a Python shell: + +.. code-block:: pycon + + >>> from my_project.skeleton import fib + >>> fib(10) + 55 + +Or if you are concerned about performing package maintainer tasks, make sure to +have tox_ installed and see what we have prepared for you out of the box:: + + tox -e docs # to build your documentation + tox -e build # to build your package distribution + tox -e publish # to test your project uploads correctly in test.pypi.org + tox -e publish -- --repository pypi # to release your package to PyPI + tox -av # to list all the tasks available + +Type ``putup -h`` to learn about :ref:`other things PyScaffold can do ` for your project, +and if you are not convinced yet, have a look on these :ref:`reasons to use PyScaffold `. + +There is also a `video tutorial`_ on how to develop a command-line application with the help of PyScaffold. + +Notes +----- + +#. PyScaffold's project template makes use of a dedicated ``src`` + folder to store all the package files meant for distribution (additional + files like tests and documentation are kept in their own separated folders). + You can find some comments and useful links about this design decision in + our :ref:`FAQ `. + +#. The ``pip install -e .`` command installs your project in editable_ mode, + making it available in import statements as any other Python module. + It might fail if your have an old version of Python's package manager and + tooling in your current environment. Please make sure you are using the + intended environment (either a `virtual environment`_ [*recommended*] or the + default installation of Python in the operating system) and try to update + them with ``python -m pip install -U pip setuptools``. + +#. If you are using a `virtual environment`_, please remember to + re-activate it everytime you close your shell, otherwise you will not be + able to import your project in the REPL_. To check if you have already + activated it you can run ``which python`` on Linux and OSX, ``where python`` + on the classical Windows command prompt, or ``Get-Command python`` on + PowerShell. + + +Examples +======== + +Just a few examples to get you an idea of how easy PyScaffold is to use: + +``putup my_little_project`` + The simplest way of using PyScaffold. A directory ``my_little_project`` is + created with a Python package named exactly the same. The MIT license will be used. + +``putup -i my_little_project`` + If you are unsure on how to use PyScaffold, or keep typing ``putup --help`` + all the time, the **experimental** ``--interactive`` (or simply ``-i``), is + your best friend. + It will open your default text editor with a file containing examples and + explanations on how to use ``putup`` (think of it as an "editable" ``--help`` + text, once the file is saved and closed all the values you leave there are + processed by PyScaffold). You might find some familiarities in the way this + option works with ``git rebase -i``, including the capacity of choosing a + different text editor by setting the ``EDITOR`` (or ``VISUAL``) environment + variable in your terminal. + +``putup skynet -l GPL-3.0-only -d "Finally, the ultimate AI!" -u http://sky.net`` + This will create a project and package named *skynet* licensed under the GPL3. + The *description* inside ``setup.cfg`` is directly set to "Finally, the ultimate AI!" + and the homepage to http://sky.net. + +``putup Scikit-Gravity -p skgravity -l BSD-3-Clause`` + This will create a project named *Scikit-Gravity* but the package will be + named *skgravity* with license new-BSD [#ex1]_. + +``putup youtub --django --pre-commit -d "Ultimate video site for hot tub fans"`` + This will create a web project and package named *youtub* that also includes + the files created by `Django's `_ + ``django-admin`` [#ex2]_. The *description* in ``setup.cfg`` will be set and + a file ``.pre-commit-config.yaml`` is created with a default setup for + `pre-commit `_. + +``putup thoroughly_tested --cirrus`` + This will create a project and package *thoroughly_tested* with files ``tox.ini`` + and ``.cirrus.yml`` for tox_ and + `Cirrus CI `_. + +``putup my_zope_subpackage --name my-zope-subpackage --namespace zope --package subpackage`` + This will create a project under the ``my_zope_subpackage`` directory with + the *installation name* of ``my-zope-subpackage`` (this is the name used by + pip_ and PyPI_), but with the following corresponding import statement:: + + from zope import subpackage + # zope is the namespace and subpackage is the package name + + To be honest, there is really only the `Zope project `_ + that comes to my mind which is using this exotic feature of Python's packaging system. + Chances are high, that you will never ever need a namespace package in your life. + To learn more about namespaces in the Python ecosystem, check `PEP 420`_. + + +.. [#ex1] Notice the usage of `SPDX identifiers`_ for specifying the license + in the CLI + +.. [#ex2] Requires the installation of pyscaffoldext-django_. + + +.. _configuration: + +Package Configuration +===================== + +Projects set up with PyScaffold rely on `setuptools`_, and therefore can be +easily configured/customised via ``setup.cfg``. Check out the example below: + +.. literalinclude:: ./example_setup.cfg + :language: ini + +You might also want to have a look on `pyproject.toml`_ for specifying +dependencies required during the build: + +.. literalinclude:: ../src/pyscaffold/templates/pyproject_toml.template + :language: toml + +Please note PyScaffold will add some internal information to ``setup.cfg``, +we do that to make updates a little smarter. + +.. note:: + To avoid splitting the configuration and build parameters among several + files, PyScaffold uses the same file as `setuptools`_ (``setup.cfg``). + Storing configuration in `pyproject.toml`_ is not supported. + In the future, if the default build metadata location changes (as proposed + by `PEP 621`_), PyScaffold will follow the same pattern. + + +.. _default-cfg: + +PyScaffold's Own Configuration +============================== + +PyScaffold also allows you to save your favourite configuration to a file that +will be automatically read every time you run ``putup``, this way you can avoid +always retyping the same command line options. + +The locations of the configuration files vary slightly across platforms, but in +general the following rule applies: + +- Linux: ``$XDG_CONFIG_HOME/pyscaffold/default.cfg`` with fallback to ``~/.config/pyscaffold/default.cfg`` +- OSX: ``~/Library/Preferences/pyscaffold/default.cfg`` +- Windows(≥7): ``%APPDATA%\pyscaffold\pyscaffold\default.cfg`` + +The file format resembles the ``setup.cfg`` generated automatically by +PyScaffold, but with only the ``metadata`` and ``pyscaffold`` sections, for +example: + +.. code-block:: ini + + [metadata] + author = John Doe + author-email = john.joe@gmail.com + license = MPL-2.0 + + [pyscaffold] + extensions = + cirrus + pre-commit + +With this file in place, typing only:: + + $ putup myproj + +will have the same effect as if you had typed:: + + $ putup --license MPL-2.0 --cirrus --pre-commit myproj + +.. note:: + + For the time being, only the following options are allowed in the config file: + + - **metadata** section: ``author``, ``author-email`` and ``license`` + - **pyscaffold** section: ``extensions`` (and associated opts) + + Options associated with extensions are the ones prefixed by an extension name. + + +To prevent PyScaffold from reading an existing config file, you can pass the +``--no-config`` option in the CLI. You can also save the given options when +creating a new project with the ``--save-config`` option. Finally, to read the +configurations from a location other then the default, use the ``--config PATH`` +option. See ``putup --help`` for more details. + +.. warning:: + + *Experimental Feature* - We are still evaluating how this new and exciting + feature will work, so its API (including file format and name) is not considered + stable and might change between minor versions. As previously stated, if + the configuration file for `setuptools`_ changes (e.g. with `PEP 621`_), + PyScaffold will follow that and change its own configuration. + + This means that in future versions, PyScaffold will likely adopt a more + `pyproject.toml`-style configuration (and as a consequence the file name + and extension might change). + + +.. _setuptools: https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html +.. _pyproject.toml: https://setuptools.readthedocs.io/en/latest/build_meta.html +.. _PEP 621: https://www.python.org/dev/peps/pep-0621/ +.. _SPDX identifiers: https://spdx.org/licenses/ +.. _pyscaffoldext-django: https://pyscaffold.org/projects/django +.. _pip: https://pip.pypa.io +.. _PyPI: https://pypi.org +.. _PEP 420: https://www.python.org/dev/peps/pep-0420/ +.. _video tutorial: https://www.youtube.com/watch?v=JwwlRkLKj7o +.. _this demo project: https://github.com/pyscaffold/pyscaffold-demo +.. _editable: https://pip.pypa.io/en/stable/reference/pip_install/#install-editable +.. _isolated development environment: https://realpython.com/python-virtual-environments-a-primer/ +.. also good, but sometimes medium can get on the way: https://towardsdatascience.com/virtual-environments-104c62d48c54 +.. _virtualenv: https://virtualenv.pypa.io +.. _conda: https://conda.io +.. _REPL: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop +.. _virtual environment: https://realpython.com/python-virtual-environments-a-primer/ +.. _tox: https://tox.readthedocs.org/