.. _reasons:

===============
Why PyScaffold?
===============

|

Stable and battle-tested
    PyScaffold was created in 2014 to make the lives of developers easier.
    Since then it has been used to create many awesome Python packages for data
    science, industrial automation, academic research, telecom, web development
    and many other sectors.

Constantly evolving
    The stability of PyScaffold does not come at the price of stagnation.
    Throughout its existence, PyScaffold has adapted itself to better solve
    the needs of its users and evolved to accommodate the best practices and
    standards of the Python ecosystem.
    In every single major release, we offered a clear update path for our users,
    automating things as much as possible, so everyone can benefit
    from PyScaffold's improvements without being afraid of breaking things.

Thoroughly tested
    PyScaffold has an extensive automated test suite that runs for all major
    operating systems and versions of Python for every commit or pull request.
    Moreover, PyScaffold is used by its maintainers in their day-to-day
    programming and for all PyScaffold's extensions, so we also have people
    constantly keeping an eye on it.

Do one thing and do it well
    It might sound old-fashioned, but we like this piece of good old UNIX wisdom.
    Pyscaffold creates a perfect project structure that compiles the best practices
    for Python packaging and has tons of useful defaults… *that is it!*

    It does not attempt to do dependency management or build a distribution,
    because there are dedicated tools exactly for that purpose which have
    survived the test of time and are well-established within the Python community.

    Instead of reinventing the wheel, we spent all these years curating a
    incredibly smart project template that ships with ready-to-use configuration
    for all the tools needed by the vast majority of Python developers.

Standing on the shoulder of giants
    PyScaffold incentives its users to use the best tools and practices
    available in the Python ecosystem.

    A generated project will contain sane default configurations for
    setuptools_ (the de facto standard for building Python packages), Sphinx_ (the one & only
    Python documentation tool), pytest_ and tox_ (most commonly used Python testing framework & task runner),
    so the users can run these common tasks using e.g. ``tox -e build``, ``tox -e docs``,
    or ``tox -e publish``.

    For those who want to go the extra mile, PyScaffold can also bring `pre-commit`_
    into the mix to run a set of prolific linters and automatic
    formatters in each commit in order to adhere to common coding standards like `pep8`_
    and `black`_.

Composable
    PyScaffold shows its strengths when combined with other tools, and indeed
    we bring configurations for lots of them by default.
    In the end of the day, a project generated by PyScaffold is just a plain,
    standard Python package, and will interoperate well with the majority of
    the tools you might want to use in your development environment.

Extensible
    *Don't like something about PyScaffold?*
    *Wish the templates were a little different?*
    *Particular workflow? Different tools?*
    *Have you got a nice set of templates that you would like to re-use?*

    Well, go ahead and make PyScaffold yours…
    We have developed a :ref:`powerful extension system <extensions>` that
    allows users to make the most out of PyScaffold. In fact, PyScaffold's core
    is very minimal and several of the options are implemented themselves as
    extensions and shipped by default.

Easy and yet powerful
    PyScaffold provides you one simple, yet powerful, command with intuitive options.
    Newcomers can achieve a lot by just running ``putup your_project_name``,
    while power users can dig into our docs/help and discover all our
    :ref:`features`.

It works with existing projects too
    PyScaffold is useful not only for starting new projects from scratch.
    If you have existing code that you have been playing around, or that was
    generated by other tools, you can convert it with PyScaffold's
    ``putup --force your_project_folder`` command. Check our :ref:`migration`
    guides.

No *lock-in*
    Once you have generated your project with PyScaffold you can later come back
    to use the update features. Other than that, there are no ties to PyScaffold at all!
    Meaning that PyScaffold will be no install dependency of your project
    and starting from version 4.0 on not even a development dependency.
    If you would want to erase all traces of the fact that you used PyScaffold
    to set up your project, we got you, and :ref:`have documented even that… <remove-pyscaffold>`

Batteries included
    PyScaffold offers a lot out of the box: we have everything a Python developer needs
    to start coding right away and be 100% productive from the start.

    Have a look in our extensive list of :ref:`features`. Using PyScaffold is
    like having a Python Packaging Guru, who has spent a lot of time researching how
    to create the best project setups, as a friend that is helping you with
    your project.


|

Curious? Checkout out our `demo project`_, or :ref:`install <installation>`
PyScaffold and type ``putup -h`` to :ref:`get started <quickstart>`.

.. _setuptools: https://setuptools.readthedocs.io/en/stable/
.. _tox: https://tox.readthedocs.io/en/stable/
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _pytest: https://docs.pytest.org/en/stable/
.. _pre-commit: https://pre-commit.com/
.. _demo project: https://github.com/pyscaffold/pyscaffold-demo
.. _pep8: https://www.python.org/dev/peps/pep-0008/
.. _black: https://black.readthedocs.io/en/stable/
