diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/rationale.rst | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/rationale.rst b/doc/rationale.rst new file mode 100644 index 0000000..559f79e --- /dev/null +++ b/doc/rationale.rst @@ -0,0 +1,58 @@ +Why use Flit? +============= + +*Make the easy things easy and the hard things possible* is an old motto from +the Perl community. Flit is entirely focused on the *easy things* part of that, +and leaves the hard things up to other tools. + +Specifically, the easy things are pure Python packages with no build steps +(neither compiling C code, nor bundling Javascript, etc.). The vast majority of +packages on PyPI are like this: plain Python code, with maybe some static data +files like icons included. + +It's easy to underestimate the challenges involved in distributing and +installing code, because it seems like you just need to copy some files into +the right place. There's a whole lot of metadata and tooling that has to work +together around that fundamental step. But with the right tooling, a developer +who wants to release their code doesn't need to know about most of that. + +What, specifically, does Flit make easy? + +- ``flit init`` helps you set up the information Flit needs about your + package. +- Subpackages are automatically included: you only need to specify the + top-level package. +- Data files within a package directory are automatically included. + Missing data files has been a common packaging mistake with other tools. +- The version number is taken from your package's ``__version__`` attribute, + so that always matches the version that tools like pip see. +- ``flit publish`` uploads a package to PyPI, so you don't need a separate tool + to do this. + +Setuptools, the most common tool for Python packaging, now has shortcuts for +many of the same things. But it has to stay compatible with projects published +many years ago, which limits what it can do by default. + +Flit also has some support for :doc:`reproducible builds <reproducible>`, +a feature which some people care about. + +There have been many other efforts to improve the user experience of Python +packaging, such as `pbr <https://pypi.org/project/pbr/>`_, but before Flit, +these tended to build on setuptools and distutils. That was a pragmatic +decision, but it's hard to build something radically different on top of those +libraries. The existence of Flit spurred the development of new standards, +like :pep:`518` and :pep:`517`, which are now used by other packaging tools +such as `Poetry <https://python-poetry.org/>`_ and +`Enscons <https://pypi.org/project/enscons/>`_. + +Other options +------------- + +If your package needs a build step, you won't be able to use Flit. +`Setuptools <https://setuptools.readthedocs.io/en/latest/>`_ is the de-facto +standard, but newer tools such as Enscons_ also cover this case. + +Flit also doesn't help you manage dependencies: you have to add them to +``pyproject.toml`` by hand. Tools like Poetry_ and `Pipenv +<https://pypi.org/project/pipenv/>`_ have features which help add and update +dependencies on other packages. |