From bbbeb2d07d4f7fd0191032c219b40565fd83454f Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 29 Apr 2024 06:26:28 +0200 Subject: Adding upstream version 3.8.0. Signed-off-by: Daniel Baumann --- doc/Makefile | 177 ++++++++++++ doc/_static/flit_logo_nobg.svg | 149 ++++++++++ doc/_static/flit_logo_nobg_cropped.png | Bin 0 -> 5890 bytes doc/_static/flit_logo_nobg_cropped.svg | 158 +++++++++++ doc/bootstrap.rst | 41 +++ doc/cmdline.rst | 262 +++++++++++++++++ doc/conf.py | 264 +++++++++++++++++ doc/development.rst | 26 ++ doc/flit_ini.rst | 113 ++++++++ doc/history.rst | 497 +++++++++++++++++++++++++++++++++ doc/index.rst | 34 +++ doc/make.bat | 242 ++++++++++++++++ doc/pyproject_toml.rst | 480 +++++++++++++++++++++++++++++++ doc/rationale.rst | 58 ++++ doc/reproducible.rst | 34 +++ doc/requirements.txt | 3 + doc/upload.rst | 77 +++++ 17 files changed, 2615 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/_static/flit_logo_nobg.svg create mode 100644 doc/_static/flit_logo_nobg_cropped.png create mode 100644 doc/_static/flit_logo_nobg_cropped.svg create mode 100644 doc/bootstrap.rst create mode 100644 doc/cmdline.rst create mode 100644 doc/conf.py create mode 100644 doc/development.rst create mode 100644 doc/flit_ini.rst create mode 100644 doc/history.rst create mode 100644 doc/index.rst create mode 100644 doc/make.bat create mode 100644 doc/pyproject_toml.rst create mode 100644 doc/rationale.rst create mode 100644 doc/reproducible.rst create mode 100644 doc/requirements.txt create mode 100644 doc/upload.rst (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..b3d458c --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Flit.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flit.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Flit" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Flit" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/_static/flit_logo_nobg.svg b/doc/_static/flit_logo_nobg.svg new file mode 100644 index 0000000..72a3e7d --- /dev/null +++ b/doc/_static/flit_logo_nobg.svg @@ -0,0 +1,149 @@ + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + diff --git a/doc/_static/flit_logo_nobg_cropped.png b/doc/_static/flit_logo_nobg_cropped.png new file mode 100644 index 0000000..5385556 Binary files /dev/null and b/doc/_static/flit_logo_nobg_cropped.png differ diff --git a/doc/_static/flit_logo_nobg_cropped.svg b/doc/_static/flit_logo_nobg_cropped.svg new file mode 100644 index 0000000..2918743 --- /dev/null +++ b/doc/_static/flit_logo_nobg_cropped.svg @@ -0,0 +1,158 @@ + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + diff --git a/doc/bootstrap.rst b/doc/bootstrap.rst new file mode 100644 index 0000000..19d7d92 --- /dev/null +++ b/doc/bootstrap.rst @@ -0,0 +1,41 @@ +Bootstrapping +============= + +Flit is itself packaged using Flit, as are some foundational packaging tools +such as ``pep517``. So where can you start if you need to install everything +from source? + +.. note:: + + For most users, ``pip`` handles all this automatically. You should only need + to deal with this if you're building things entirely from scratch, such as + putting Python packages into another package format. + +The key piece is ``flit_core``. This is a package which can build itself using +nothing except Python and the standard library. From an unpacked source archive, +you can make a wheel by running:: + + python -m flit_core.wheel + +And then you can install this wheel with the ``bootstrap_install.py`` script +included in the sdist (or by unzipping it to the correct directory):: + + # Install to site-packages for this Python: + python bootstrap_install.py dist/flit_core-*.whl + + # Install somewhere else: + python bootstrap_install.py --installdir /path/to/site-packages dist/flit_core-*.whl + +As of version 3.6, flit_core bundles the ``tomli`` TOML parser, to avoid a +dependency cycle. If you need to unbundle it, you will need to special-case +installing flit_core and/or tomli to get around that cycle. + +After ``flit_core``, I recommend that you get `installer +`_ set up. You can use +``python -m flit_core.wheel`` again to make a wheel, and then use installer +itself (from the source directory) to install it. + +After that, you probably want to get `build `_ +and its dependencies installed as the goal of the bootstrapping phase. You can +then use ``build`` to create wheels of any other Python packages, and +``installer`` to install them. diff --git a/doc/cmdline.rst b/doc/cmdline.rst new file mode 100644 index 0000000..c443ddd --- /dev/null +++ b/doc/cmdline.rst @@ -0,0 +1,262 @@ +Flit command line interface +=========================== + +All operations use the ``flit`` command, followed by one of a number of +subcommands. + +Common options +-------------- + +.. program:: flit + +.. option:: -f , --ini-file + + Path to a config file specifying the module to build. The default is + ``pyproject.toml``. + +.. option:: --version + + Show the version of Flit in use. + +.. option:: --help + + Show help on the command-line interface. + +.. option:: --debug + + Show more detailed logs about what flit is doing. + +.. _build_cmd: + +``flit build`` +-------------- + +.. program:: flit build + +Build a wheel and an sdist (tarball) from the package. + +.. option:: --format + + Limit to building either ``wheel`` or ``sdist``. + +.. option:: --setup-py + + Generate a ``setup.py`` file in the sdist, so it can be installed by older + versions of pip. + +.. option:: --no-setup-py + + Don't generate a setup.py file in the sdist. This is the default. + An sdist built without this will only work with tools that support PEP 517, + but the wheel will still be usable by any compatible tool. + + .. versionchanged:: 3.5 + + Generating ``setup.py`` disabled by default. + +.. _publish_cmd: + +``flit publish`` +---------------- + +.. program:: flit publish + +Build a wheel and an sdist (tarball) from the package, and upload them to PyPI +or another repository. + +.. option:: --format + + Limit to publishing either ``wheel`` or ``sdist``. + You should normally publish the two formats together. + +.. option:: --setup-py + + Generate a ``setup.py`` file in the sdist, so it can be installed by older + versions of pip. + +.. option:: --no-setup-py + + Don't generate a setup.py file in the sdist. This is the default. + An sdist built without this will only work with tools that support PEP 517, + but the wheel will still be usable by any compatible tool. + + .. versionchanged:: 3.5 + + Generating ``setup.py`` disabled by default. + +.. option:: --repository + + Name of a repository to upload packages to. Should match a section in + ``~/.pypirc``. The default is ``pypi``. + +.. option:: --pypirc + + The .pypirc config file to be used. The default is ``~/.pypirc``. + +.. seealso:: :doc:`upload` + +.. _install_cmd: + +``flit install`` +---------------- + +.. program:: flit install + +Install the package on your system. + +By default, the package is installed to the same Python environment that Flit +itself is installed in; use :option:`--python` or :envvar:`FLIT_INSTALL_PYTHON` +to override this. + +If you don't have permission to modify the environment (e.g. the system Python +on Linux), Flit may do a user install instead. Use the :option:`--user` or +:option:`--env` flags to force this one way or the other, rather than letting +Flit guess. + +.. option:: -s, --symlink + + Symlink the module into site-packages rather than copying it, so that you + can test changes without reinstalling the module. + +.. option:: --pth-file + + Create a ``.pth`` file in site-packages rather than copying the module, so + you can test changes without reinstalling. This is a less elegant alternative + to ``--symlink``, but it works on Windows, which typically doesn't allow + symlinks. + +.. option:: --deps + + Which dependencies to install. One of ``all``, ``production``, ``develop``, + or ``none``. ``all`` and ``develop`` install the extras ``test``, ``doc``, + and ``dev``. Default ``all``. + +.. option:: --extras + + Which named extra features to install dependencies for. Specify ``all`` to + install all optional dependencies, or a comma-separated list of extras. + Default depends on ``--deps``. + +.. option:: --only-deps + + Install the dependencies of this package, but not the package itself. + + This can be useful for e.g. building a container image, where your own code + is copied or mounted into the container at a later stage. + + .. versionadded:: 3.8 + +.. option:: --user + + Do a user-local installation. This is the default if flit is not in a + virtualenv or conda env (if the environment's library directory is + read-only and ``site.ENABLE_USER_SITE`` is true). + +.. option:: --env + + Install into the environment - the opposite of :option:`--user`. + This is the default in a virtualenv or conda env (if the environment's + library directory is writable or ``site.ENABLE_USER_SITE`` is false). + +.. option:: --python + + Install for another Python, identified by the path of the python + executable. Using this option, you can install a module for Python 2, for + instance. See :envvar:`FLIT_INSTALL_PYTHON` if this option is not given. + + .. versionchanged:: 2.1 + Added :envvar:`FLIT_INSTALL_PYTHON` and use its value over the Python + running Flit when an explicit :option:`--python` option is not given. + +.. note:: + + Flit calls pip to do the installation. You can set any of pip's options + `using its environment variables + `__. + + When you use the :option:`--symlink` or :option:`--pth-file` options, pip + is used to install dependencies. Otherwise, Flit builds a wheel and then + calls pip to install that. + +.. _init_cmd: + +``flit init`` +------------- + +.. program:: flit init + +Create a new ``pyproject.toml`` config file by prompting for information about +the module in the current directory. + +Environment variables +--------------------- + +.. envvar:: FLIT_NO_NETWORK + + .. versionadded:: 0.10 + + Setting this to any non-empty value will stop flit from making network + connections (unless you explicitly ask to upload a package). This + is intended for downstream packagers, so if you use this, it's up to you to + ensure any necessary dependencies are installed. + +.. envvar:: FLIT_ROOT_INSTALL + + By default, ``flit install`` will fail when run as root on POSIX systems, + because installing Python modules systemwide is not recommended. Setting + this to any non-empty value allows installation as root. It has no effect on + Windows. + +.. envvar:: FLIT_USERNAME + FLIT_PASSWORD + FLIT_INDEX_URL + + .. versionadded:: 0.11 + + Set a username, password, and index URL for uploading packages. + See :ref:`uploading packages with environment variables ` + for more information. + + Token-based upload to PyPI is supported. To upload using a PyPI token, + set ``FLIT_USERNAME`` to ``__token__``, and ``FLIT_PASSWORD`` to the + token value. + +.. envvar:: FLIT_ALLOW_INVALID + + .. versionadded:: 0.13 + + Setting this to any non-empty value tells Flit to continue if it detects + invalid metadata, instead of failing with an error. Problems will still be + reported in the logs, but won't cause Flit to stop. + + If the metadata is invalid, uploading the package to PyPI may fail. This + environment variable provides an escape hatch in case Flit incorrectly + rejects your valid metadata. If you need to use it and you believe your + metadata is valid, please `open an issue `__. + +.. envvar:: FLIT_INSTALL_PYTHON + + .. versionadded:: 2.1 + + .. program:: flit install + + Set a default Python interpreter for :ref:`install_cmd` to use when + :option:`--python` is not specified. The value can be either an absolute + path, or a command name (which will be found in ``PATH``). If this is unset + or empty, the module is installed for the copy of Python that is running + Flit. + +.. envvar:: SOURCE_DATE_EPOCH + + To make reproducible builds, set this to a timestamp as a number of seconds + since the start of the year 1970 in UTC, and document the value you used. + On Unix systems, you can get a value for the current time by running:: + + date +%s + + + .. seealso:: + + `The SOURCE_DATE_EPOCH specification + `__ + diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..cce9bee --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,264 @@ +# -*- coding: utf-8 -*- +# +# Flit documentation build configuration file, created by +# sphinx-quickstart on Sun Mar 15 19:16:41 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinxcontrib_github_alt', + 'sphinx_rtd_theme', +] + +github_project_url = "https://github.com/pypa/flit" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Flit' +copyright = u'2015, Thomas Kluyver' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '3.8.0' +# The full version, including alpha/beta/rc tags. +release = version #+ '.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = '_static/flit_logo_nobg_cropped.svg' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Flitdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'Flit.tex', u'Flit Documentation', + u'Thomas Kluyver', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'flit', u'Flit Documentation', + [u'Thomas Kluyver'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Flit', u'Flit Documentation', + u'Thomas Kluyver', 'Flit', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/doc/development.rst b/doc/development.rst new file mode 100644 index 0000000..18090af --- /dev/null +++ b/doc/development.rst @@ -0,0 +1,26 @@ +Developing Flit +=============== + +To get a development installation of Flit itself:: + + git clone https://github.com/pypa/flit.git + cd flit + python3 -m pip install docutils requests + python3 bootstrap_dev.py + +This links Flit into the current Python environment, so you can make changes +and try them without having to reinstall each time. + +Testing +------- + +To run the tests in separate environments for each available Python version:: + + tox + +`tox `_ has many options. + +To run the tests in your current environment, run:: + + pytest + diff --git a/doc/flit_ini.rst b/doc/flit_ini.rst new file mode 100644 index 0000000..b41d967 --- /dev/null +++ b/doc/flit_ini.rst @@ -0,0 +1,113 @@ +:orphan: + +The flit.ini config file +======================== + +This file lives next to the module or package. + +.. note:: + + Flit 0.12 and above uses a :doc:`pyproject.toml file ` file + to store this information. Run ``python3 -m flit.tomlify`` to convert a + ``flit.ini`` file to ``pyproject.toml``. + +Metadata section +---------------- + +There are four required fields: + +module + The name of the module/package, as you'd use in an import statement. +author + Your name +author-email + Your email address +home-page + A URL for the project, such as its Github repository. + +e.g. for flit itself + +.. code-block:: ini + + [metadata] + module=flit + author=Thomas Kluyver + author-email=thomas@kluyver.me.uk + home-page=https://github.com/pypa/flit + +The remaining fields are optional: + +requires + A list of other packages from PyPI that this package needs. Each package + should be on its own line, and may be followed by a version specifier in + parentheses, like ``(>=4.1)``, and/or an `environment marker + `_ + after a semicolon. For example: + + .. code-block:: ini + + requires = requests (>=2.6) + configparser; python_version == '2.7' + +dev-requires + Packages that are required for development. This field is in the same format + as ``requires``. + + These are not (yet) encoded in the wheel, but are used when doing + ``flit install``. +description-file + A path (relative to the .ini file) to a file containing a longer description + of your package to show on PyPI. This should be written in `reStructuredText + `_, if your long + description is not valid reStructuredText, a warning will be printed, + and it will be interpreted as plain text on PyPI. +classifiers + A list of `Trove classifiers `_, + one per line, indented. +requires-python + A version specifier for the versions of Python this requires, e.g. ``~=3.3`` or + ``>=3.3,<4`` which are equivalents. +dist-name + If you want your package's name on PyPI to be different from the importable + module name, set this to the PyPI name. +keywords + Comma separated list of words to help with searching for your package. +license + The name of a license, if you're using one for which there isn't a Trove + classifier. It's recommended to use Trove classifiers instead of this in + most cases. +maintainer, maintainer-email + Like author, for if you've taken over a project from someone else. + +Here's the full example from flit itself: + +.. code-block:: ini + + [metadata] + author=Thomas Kluyver + author-email=thomas@kluyver.me.uk + home-page=https://github.com/pypa/flit + requires=requests + requires-python= >=3 + description-file=README.rst + classifiers=Intended Audience :: Developers + License :: OSI Approved :: BSD License + Programming Language :: Python :: 3 + Topic :: Software Development :: Libraries :: Python Modules + +.. _flit_ini_scripts: + +Scripts section +--------------- + +Each key and value in this describes a shell command to be installed along with +your package. These work like setuptools 'entry points'. Here's the section +for flit: + +.. code-block:: ini + + [scripts] + flit = flit:main + +This will create a ``flit`` command, which will call the function ``main()`` +imported from :mod:`flit`. diff --git a/doc/history.rst b/doc/history.rst new file mode 100644 index 0000000..e04e1fb --- /dev/null +++ b/doc/history.rst @@ -0,0 +1,497 @@ +Release history +=============== + +Version 3.8 +----------- + +- A project name containing hyphens is now automatically translated to use + underscores for the import name (:ghpull:`566`). +- New option :option:`flit install --only-deps` to install the dependencies of + the package, but not the package itself. +- Add support for recursive globbing (``**``) in sdist includes and excludes + (:ghpull:`550`). +- Python's bytecode cache files (``__pycache__`` folders and ``.pyc`` files) + are now always excluded from sdists (:ghpull:`581`). +- Use tomllib in Python 3.11, rather than tomli (:ghpull:`573`, :ghpull:`604`). +- Fix crash when unable to get a password from ``keyring`` (:ghpull:`567`). +- Fix including modified files in sdist when using Mercurial (:ghpull:`541`). +- Fix for some cases of determining whether a package supports Python 2 or not + (:ghpull:`593`). +- Fix parsing version number from code using multiple assignments (:ghpull:`474`). +- Document how to use a PyPI token with :envvar:`FLIT_PASSWORD` (:ghpull:`602`). +- Fix link to information about environment variables for pip (:ghpull:`576`). +- Link to the docs for the latest stable version in package metadata + (:ghpull:`589`). +- Remove a mention of the ``toml`` package, which is no longer needed, from the + :doc:`development` page (:ghpull:`601`). +- The :doc:`bootstrap ` install script for ``flit_core`` accepts a + new ``--install-root`` option. +- Ensure the license file is included in packages on PyPI (:ghpull:`603`). + +Version 3.7.1 +------------- + +- Fix building packages which need execution to get the version number, + and have a relative import in ``__init__.py`` (:ghpull:`531`). + +Version 3.7 +----------- + +- Support for :ref:`external data files ` such + as man pages or Jupyter extension support files (:ghpull:`510`). +- Project names are now lowercase in wheel filenames and ``.dist-info`` folder + names, in line with the specifications (:ghpull:`498`). +- Improved support for :doc:`bootstrapping ` a Python environment, + e.g. for downstream packagers (:ghpull:`511`). ``flit_core.wheel`` is usable + with ``python -m`` to create wheels before the `build `_ + tool is available, and ``flit_core`` sdists also include a script to install + itself from a wheel before `installer `_ + is available. +- Use newer importlib APIs, fixing some deprecation warnings (:ghpull:`499`). + +Version 3.6 +----------- + +- ``flit_core`` now bundles the `tomli `_ TOML + parser library (version 1.2.3) to avoid a circular dependency between + ``flit_core`` and ``tomli`` (:ghpull:`492`). This means ``flit_core`` now has + no dependencies except Python itself, both at build time and at runtime, + simplifying :doc:`bootstrapping `. + +Version 3.5.1 +------------- + +- Fix development installs with ``flit install --symlink`` and ``--pth-file``, + which were broken in 3.5.0, especially for packages using a ``src`` folder + (:ghpull:`472`). + +Version 3.5 +----------- + +- You can now use Flit to distribute a module or package inside a namespace + package (as defined by :pep:`420`). To do this, specify the import name of the + concrete, inner module you are packaging - e.g. ``name = "sphinxcontrib.foo"`` + - either in the ``[project]`` table, or under ``[tool.flit.module]`` if you + want to use a different name on PyPI (:ghpull:`468`). +- Flit no longer generates a ``setup.py`` file in sdists (``.tar.gz`` packages) + by default (:ghpull:`462`). Modern packaging tools don't need this. You can + use the ``--setup-py`` flag to keep adding it for now, but this will probably + be removed at some point in the future. +- Fixed how ``flit init`` handles authors' names with non-ASCII characters + (:ghpull:`460`). +- When ``flit init`` generates a LICENSE file, the new ``pyproject.toml`` now + references it (:ghpull:`467`). + +Version 3.4 +----------- + +- Python 3.6 or above is now required, both for ``flit`` and ``flit_core``. +- Add a ``--setup-py`` option to ``flit build`` and ``flit publish``, and a + warning when neither this nor ``--no-setup-py`` are specified (:ghpull:`431`). + A future version will stop generating ``setup.py`` files in sdists by default. +- Add support for standardised editable installs - ``pip install -e`` - + according to :pep:`660` (:ghpull:`400`). +- Add a ``--pypirc`` option for ``flit publish`` to specify an alternative path + to a ``.pypirc`` config file describing package indexes (:ghpull:`434`). +- Fix installing dependencies specified in a ``[project]`` table (:ghpull:`433`). +- Fix building wheels when ``SOURCE_DATE_EPOCH`` (see :doc:`reproducible`) is + set to a date before 1980 (:ghpull:`448`). +- Switch to using the `tomli `_ TOML parser, + in common with other packaging projects (:ghpull:`438`). + This supports TOML version 1.0. +- Add a document on :doc:`bootstrap` (:ghpull:`441`). + +Version 3.3 +----------- + +- ``PKG-INFO`` files in sdists are now generated the same way as ``METADATA`` in + wheels, fixing some issues with sdists (:ghpull:`410`). +- ``flit publish`` now sends SHA-256 hashes, fixing uploads to GitLab package + repositories (:ghpull:`416`). +- The ``[project]`` metadata table from :pep:`621` is now fully supported and + :ref:`documented `. Projects using this can now + specify ``requires = ["flit_core >=3.2,<4"]`` in the ``[build-system]`` table. + +Version 3.2 +----------- + +- Experimental support for specifying metadata in a ``[project]`` table in + ``pyproject.toml`` as specified by :pep:`621` (:ghpull:`393`). If you try + using this, please specify ``requires = ["flit_core >=3.2.0,<3.3"]`` in the + ``[build-system]`` table for now, in case it needs to change for the next + release. +- Fix writing METADATA file with multi-line information in certain fields + such as ``Author`` (:ghpull:`402`). +- Fix building wheel when a directory such as LICENSES appears in the project + root directory (:ghpull:`401`). + +Version 3.1 +----------- + +- Update handling of names & version numbers in wheel filenames and + ``.dist-info`` folders in line with changes in the specs (:ghpull:`395`). +- Switch from the deprecated ``pytoml`` package to ``toml`` (:ghpull:`378`). +- Fix specifying backend-path in ``pyproject.toml`` for flit-core (as a list + instead of a string). + +Version 3.0 +----------- + +Breaking changes: + +- Projects must now provide Flit with information in ``pyproject.toml`` files, + not the older ``flit.ini`` format (:ghpull:`338`). +- ``flit_core`` once again requires Python 3 (>=3.4). Packages that support + Python 2 can still be built by ``flit_core`` 2.x, but can't rely on new + features (:ghpull:`342`). +- The deprecated ``flit installfrom`` command was removed (:ghpull:`334`). + You can use ``pip install git+https://github.com/...`` instead. + +Features and fixes: + +- Fix building sdists from a git repository with non-ASCII characters in + filenames (:ghpull:`346`). +- Fix identifying the version number when the code contains a subscript + assignment before ``__version__ =`` (:ghpull:`348`). +- Script entry points can now use a class method (:ghpull:`359`). +- Set suitable permission bits on metadata files in wheels (:ghpull:`256`). +- Fixed line endings in the ``RECORD`` file when installing on Windows + (:ghpull:`368`). +- Support for recording the source of local installations, as in :pep:`610` + (:ghpull:`335`). +- ``flit init`` will check for a README in the root of the project and + automatically set it as ``description-file`` (:ghpull:`337`). +- Pygments is not required for checking reStructuredText READMEs (:ghpull:`357`). +- Packages where the version number can be recognised without executing their + code don't need their dependencies installed to build, which should make them + build faster (:ghpull:`361`). +- Ensure the installed ``RECORD`` file is predictably ordered (:ghpull:`366`). + +Version 2.3 +----------- + +- New projects created with :ref:`init_cmd` now declare that they require + ``flit_core >=2,<4`` (:ghpull:`328`). Any projects using ``pyproject.toml`` + (not ``flit.ini``) should be compatible with flit 3.x. +- Fix selecting files from a git submodule to include in an sdist + (:ghpull:`324`). +- Fix checking classifiers when no writeable cache directory is available + (:ghpull:`319`). +- Better errors when trying to install to a mis-spelled or missing Python + interpreter (:ghpull:`331`). +- Fix specifying ``--repository`` before ``upload`` (:ghpull:`322`). Passing the + option like this is deprecated, and you should now pass it after ``upload``. +- Documentation improvements (:ghpull:`327`, :ghpull:`318`, :ghpull:`314`) + +Version 2.2 +----------- + +- Allow underscores in package names with Python 2 (:ghpull:`305`). +- Add a ``--no-setup-py`` option to build sdists without a backwards-compatible + ``setup.py`` file (:ghpull:`311`). +- Fix the generated ``setup.py`` file for packages using a ``src/`` layout + (:ghpull:`303`). +- Fix detecting when more than one file matches the module name specified + (:ghpull:`307`). +- Fix installing to a venv on Windows with the ``--python`` option + (:ghpull:`300`). +- Don't echo the command in scripts installed with ``--symlink`` or + ``--pth-file`` on Windows (:ghpull:`310`). +- New ``bootstrap_dev.py`` script to set up a development installation of Flit + from the repository (:ghpull:`301`, :ghpull:`306`). + +Version 2.1 +----------- + +- Use compression when adding files to wheels. +- Added the :envvar:`FLIT_INSTALL_PYTHON` environment variable (:ghpull:`295`), + to configure flit to always install into a Python other than the one it's + running on. +- ``flit_core`` uses the ``intreehooks`` shim package to load its bootstrapping + backend, until a released version of pip supports the standard + ``backend-path`` mechanism. + +Version 2.0 +----------- + +Flit 2 is a major architecture change. The ``flit_core`` package now provides +a :pep:`517` backend for building packages, while ``flit`` is a +:doc:`command line interface ` extending that. + +The build backend works on Python 2, so tools like pip should be able to install +packages built with flit from source on Python 2. +The ``flit`` command requires Python 3.5 or above. +You will need to change the build-system table in your ``pyproject.toml`` file +to look like this: + +.. code-block:: toml + + [build-system] + requires = ["flit_core >=2,<4"] + build-backend = "flit_core.buildapi" + +Other changes include: + +- Support for storing your code under a ``src/`` folder (:ghpull:`260`). + You don't need to change any configuration if you do this. +- Options to control what files are included in an sdist - see + :ref:`pyproject_toml_sdist` for the details. +- Requirements can specify a URL 'direct reference', as an alternative to a + version number, with the syntax defined in :pep:`440`: + ``requests @ https://example.com/requests-2.22.0.tar.gz``. +- Fix the shebang of scripts installed with the ``--python`` option and the + ``--symlink`` flag (:ghpull:`286`). +- Installing with ``--deps develop`` now installs normal dependencies + as well as development dependencies. +- Author email is no longer required in the metadata table (:ghpull:`289`). +- More error messages are now shown without a traceback (:ghpull:`254`) + +Version 1.3 +----------- + +- Fix for building sdists from a subdirectory in a Mercurial repository + (:ghpull:`233`). +- Fix for getting the docstring and version from modules defining their encoding + (:ghpull:`239`). +- Fix for installing packages with ``flit installfrom`` (:ghpull:`221`). +- Packages with requirements no longer get a spurious ``Provides-Extra: .none`` + metadata entry (:ghissue:`228`). +- Better check of whether ``python-requires`` includes any Python 2 version + (:ghpull:`232`). +- Better check of home page URLs in ``flit init`` (:ghpull:`230`). +- Better error message when the description file is not found (:ghpull:`234`). +- Updated a help message to refer to ``pyproject.toml`` (:ghpull:`240`). +- Improve tests of ``flit init`` (:ghpull:`229`). + +Version 1.2.1 +------------- + +- Fix for installing packages with ``flit install``. +- Make ``requests_download`` an extra dependency, to avoid a circular build + dependency. To use ``flit installfrom``, you can install with + ``pip install flit[installfrom]``. Note that the ``installfrom`` subcommand + is deprecated, as it will soon be possible to use pip to install Flit projects + directly from a VCS URL. + +Version 1.2 +----------- + +- Fixes for packages specifying ``requires-extra``: sdists should now work, and + environment markers can be used together with ``requires-extra``. +- Fix running ``flit installfrom`` without a config file present in the + working directory. +- The error message for a missing or empty docstring tells you what file + the docstring should be in. +- Improvements to documentation on version selectors for requirements. + +Version 1.1 +----------- + +- Packages can now have 'extras', specified as ``requires-extra`` in the + :doc:`pyproject.toml file `. These are additional dependencies + for optional features. +- The ``home-page`` metadata field is no longer required. +- Additional project URLs are now validated. +- ``flit -V`` is now equivalent to ``flit --version``. +- Various improvements to documentation. + +Version 1.0 +----------- + +- The description file may now be written in reStructuredText, Markdown or + plain text. The file extension should indicate which of these formats it is + (``.rst``, ``.md`` or ``.txt``). Previously, only reStructuredText was + officially supported. +- Multiple links (e.g. documentation, bug tracker) can now be specified in a + new :ref:`[tool.flit.metadata.urls] section ` of + ``pyproject.toml``. +- Dependencies are now correctly installed to the target Python when you use + the ``--symlink`` or ``--pth-file`` options. +- Dependencies are only installed to the Python where Flit is running if + it fails to get the docstring and version number without them. +- The commands deprecated in 0.13—``flit wheel``, ``flit sdist`` and + ``flit register``—have been removed. + +Although version 1.0 sounds like a milestone, there's nothing that makes this +release especially significant. It doesn't represent a step change in stability +or completeness. Flit has been gradually maturing for some time, and I chose +this point to end the series of 0.x version numbers. + +Version 0.13 +------------ + +- Better validation of several metadata fields (``dist-name``, ``requires``, + ``requires-python``, ``home-page``), and of the version number. +- New :envvar:`FLIT_ALLOW_INVALID` environment variable to ignore validation + failures in case they go wrong. +- The list of valid classifiers is now fetched from Warehouse (https://pypi.org), + rather than the older https://pypi.python.org site. +- Deprecated ``flit wheel`` and ``flit sdist`` subcommands: use + :ref:`build_cmd`. +- Deprecated ``flit register``: you can no longer register a package separately + from uploading it. + +Version 0.12.3 +-------------- + +- Fix building and installing packages with a ``-`` in the distribution name. +- Fix numbering in README. + +Version 0.12.2 +-------------- + +- New tool to convert ``flit.ini`` to ``pyproject.toml``:: + + python3 -m flit.tomlify + +- Use the PAX tar format for sdists, as specified by PEP 517. + +Version 0.12.1 +-------------- + +- Restore dependency on ``zipfile36`` backport package. +- Add some missing options to documentation of ``flit install`` subcommand. +- Rearrange environment variables in the docs. + +Version 0.12 +------------ + +- Switch the config to ``pyproject.toml`` by default instead of ``flit.ini``, + and implement the PEP 517 API. +- A new option ``--pth-file`` allows for development installation on Windows + (where ``--symlink`` usually won't work). +- Normalise file permissions in the zip file, making builds more reproducible + across different systems. +- Sdists (.tar.gz packages) can now also be reproducibly built by setting + :envvar:`SOURCE_DATE_EPOCH`. +- For most modules, Flit can now extract the version number and docstring + without importing it. It will still fall back to importing where getting + these from the AST fails. +- ``flit build`` will build the wheel from the sdist, helping to ensure that + files aren't left out of the sdist. +- All list fields in the INI file now ignore blank lines (``requires``, + ``dev-requires``, ``classifiers``). +- Fix the path separator in the ``RECORD`` file of a wheel built on Windows. +- Some minor fixes to building reproducible wheels. +- If building a wheel fails, the temporary file created will be cleaned up. +- Various improvements to docs and README. + +Version 0.11.4 +-------------- + +- Explicitly open various files as UTF-8, rather than relying on locale + encoding. +- Link to docs from README. +- Better test coverage, and a few minor fixes for problems revealed by tests. + +Version 0.11.3 +-------------- + +- Fixed a bug causing failed uploads when the password is entered in the + terminal. + +Version 0.11.2 +-------------- + +- A couple of behaviour changes when uploading to warehouse. + +Version 0.11.1 +-------------- + +- Fixed a bug when you use flit to build an sdist from a subdirectory inside a + VCS checkout. The VCS is now correctly detected. +- Fix the rst checker for newer versions of docutils, by upgrading the bundled + copy of readme_renderer. + +Version 0.11 +------------ + +- Flit can now build sdists (tarballs) and upload them to PyPI, if your code is + in a git or mercurial repository. There are new commands: + + - ``flit build`` builds both a wheel and an sdist. + - ``flit publish`` builds and uploads a wheel and an sdist. + +- Smarter ways of getting the information needed for upload: + + - If you have the `keyring `_ package + installed, flit can use it to store your password, rather than keeping it + in plain text in ``~/.pypirc``. + - If ``~/.pypirc`` does not already exist, and you are prompted for your + username, flit will write it into that file. + - You can provide the information as environment variables: + :envvar:`FLIT_USERNAME`, :envvar:`FLIT_PASSWORD` and :envvar:`FLIT_INDEX_URL`. + Use this to upload packages from a CI service, for instance. + +- Include 'LICENSE' or 'COPYING' files in wheels. +- Fix for ``flit install --symlink`` inside a virtualenv. + + +Version 0.10 +------------ + +- Downstream packagers can use the :envvar:`FLIT_NO_NETWORK` environment + variable to stop flit downloading data from the network. + +Version 0.9 +----------- + +- ``flit install`` and ``flit installfrom`` now take an optional ``--python`` argument, + with the path to the Python executable you want to install it for. + Using this, you can install modules to Python 2. +- Installing a module normally (without ``--symlink``) builds a wheel and uses + pip to install it, which should work better in some corner cases. + +Version 0.8 +----------- + +- A new ``flit installfrom`` subcommand to install a project from a source + archive, such as from Github. +- :doc:`Reproducible builds ` - you can produce byte-for-byte + identical wheels. +- A warning for non-canonical version numbers according to `PEP 440 + `__. +- Fix for installing projects on Windows. +- Better error message when module docstring is only whitespace. + +Version 0.7 +----------- + +- A new ``dev-requires`` field in the config file for development requirements, + used when doing ``flit install``. +- Added a ``--deps`` option for ``flit install`` to control which dependencies + are installed. +- Flit can now be invoked with ``python -m flit``. + +Version 0.6 +----------- + +- ``flit install`` now ensures requirements specified in ``flit.ini`` are + installed, using pip. +- If you specify a description file, flit now warns you if it's not valid + reStructuredText (since invalid reStructuredText is treated as plain text on + PyPI). +- Improved the error message for mis-spelled keys in ``flit.ini``. + +Version 0.5 +----------- + +- A new ``flit init`` command to quickly define the essential basic metadata + for a package. +- Support for entry points. +- A new ``flit register`` command to register a package without uploading it, + for when you want to claim a name before you're ready to release. +- Added a ``--repository`` option for specifying an alternative PyPI instance. +- Added a ``--debug`` flag to show debug-level log messages. +- Better error messages when the module docstring or ``__version__`` is missing. + +Version 0.4 +----------- + +- Users can now specify ``dist-name`` in the config file if they need to use + different names on PyPI and for imports. +- Classifiers are now checked against a locally cached list of valid + classifiers. +- Packages can be locally installed into environments for development. +- Local installation now creates a PEP 376 ``.dist-info`` folder instead of + ``.egg-info``. diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..9740a9c --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,34 @@ +Flit |version| +============== + +.. raw:: html + + + +.. include:: ../README.rst + +Documentation contents +---------------------- + +.. toctree:: + :maxdepth: 2 + + pyproject_toml + cmdline + upload + reproducible + rationale + bootstrap + +.. toctree:: + :maxdepth: 1 + + development + history + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..965332d --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Flit.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Flit.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/doc/pyproject_toml.rst b/doc/pyproject_toml.rst new file mode 100644 index 0000000..18d1d26 --- /dev/null +++ b/doc/pyproject_toml.rst @@ -0,0 +1,480 @@ +The pyproject.toml config file +============================== + +This file lives next to the module or package. + +.. note:: + + Older version of Flit (up to 0.11) used a :doc:`flit.ini file ` for + similar information. These files no longer work with Flit 3 and above. + + Run ``python3 -m flit.tomlify`` to convert a ``flit.ini`` file to + ``pyproject.toml``. + +Build system section +-------------------- + +This tells tools like pip to build your project with flit. It's a standard +defined by PEP 517. For any new project using Flit, it will look like this: + +.. code-block:: toml + + [build-system] + requires = ["flit_core >=3.2,<4"] + build-backend = "flit_core.buildapi" + +Version constraints: + +- For now, all packages should specify ``<4``, so they won't be impacted by + changes in the next major version. +- :ref:`pyproject_toml_project` requires ``flit_core >=3.2`` +- :ref:`pyproject_old_metadata` requires ``flit_core >=2,<4`` +- The older :doc:`flit.ini file ` requires ``flit_core <3``. +- TOML features new in version 1.0 require ``flit_core >=3.4``. +- ``flit_core`` 3.3 is the last version supporting Python 3.4 & 3.5. Packages + supporting these Python versions can only use `TOML v0.5 + `_. +- Only ``flit_core`` 2.x can build packages on Python 2, so packages still + supporting Python 2 cannot use new-style metadata (the ``[project]`` table). + +.. _pyproject_toml_project: + +New style metadata +------------------ + +.. versionadded:: 3.2 + +The new standard way to specify project metadata is in a ``[project]`` table, +as defined by :pep:`621`. Flit works for now with either this or the older +``[tool.flit.metadata]`` table (:ref:`described below `), +but it won't allow you to mix them. + +A simple ``[project]`` table might look like this: + +.. code-block:: toml + + [project] + name = "astcheck" + authors = [ + {name = "Thomas Kluyver", email = "thomas@kluyver.me.uk"}, + ] + readme = "README.rst" + classifiers = [ + "License :: OSI Approved :: MIT License", + ] + requires-python = ">=3.5" + dynamic = ["version", "description"] + +The allowed fields are: + +name + The name your package will have on PyPI. This field is required. For Flit, + this name, with any hyphens replaced by underscores, is also the default value + of the import name (see :ref:`pyproject_module` if that needs to be + different). + + .. versionchanged:: 3.8 + Hyphens in the project name are now translated to underscores for the + import name. +version + Version number as a string. If you want Flit to get this from a + ``__version__`` attribute, leave it out of the TOML config and include + "version" in the ``dynamic`` field. +description + A one-line description of your project. If you want Flit to get this from + the module docstring, leave it out of the TOML config and include + "description" in the ``dynamic`` field. +readme + A path (relative to the .toml file) to a file containing a longer description + of your package to show on PyPI. This should be written in `reStructuredText + `_, Markdown or + plain text, and the filename should have the appropriate extension + (``.rst``, ``.md`` or ``.txt``). Alternatively, ``readme`` can be a table with + either a ``file`` key (a relative path) or a ``text`` key (literal text), and + an optional ``content-type`` key (e.g. ``text/x-rst``). +requires-python + A version specifier for the versions of Python this requires, e.g. ``~=3.3`` or + ``>=3.3,<4``, which are equivalents. +license + A table with either a ``file`` key (a relative path to a license file) or a + ``text`` key (the license text). +authors + A list of tables with ``name`` and ``email`` keys (both optional) describing + the authors of the project. +maintainers + Same format as authors. +keywords + A list of words to help with searching for your package. +classifiers + A list of `Trove classifiers `_. + Add ``Private :: Do Not Upload`` into the list to prevent a private package + from being uploaded to PyPI by accident. +dependencies & optional-dependencies + See :ref:`pyproject_project_dependencies`. +urls + See :ref:`pyproject_project_urls`. +scripts & gui-scripts + See :ref:`pyproject_project_scripts`. +entry-points + See :ref:`pyproject_project_entrypoints`. +dynamic + A list of field names which aren't specified here, for which Flit should + find a value at build time. Only "version" and "description" are accepted. + +.. _pyproject_project_dependencies: + +Dependencies +~~~~~~~~~~~~ + +The ``dependencies`` field is a list of other packages from PyPI that this +package needs. Each package may be followed by a version specifier like +``>=4.1``, and/or an `environment marker`_ +after a semicolon. For example: + + .. code-block:: toml + + dependencies = [ + "requests >=2.6", + "configparser; python_version == '2.7'", + ] + +The ``[project.optional-dependencies]`` table contains lists of packages needed +for every optional feature. The requirements are specified in the same format as +for ``dependencies``. For example: + + .. code-block:: toml + + [project.optional-dependencies] + test = [ + "pytest >=2.7.3", + "pytest-cov", + ] + doc = ["sphinx"] + +You can call these optional features anything you want, although ``test`` and +``doc`` are common ones. You specify them for installation in square brackets +after the package name or directory, e.g. ``pip install '.[test]'``. + +.. _pyproject_project_urls: + +URLs table +~~~~~~~~~~ + +Your project's page on `pypi.org `_ can show a number of +links. You can point people to documentation or a bug tracker, for example. + +This section is called ``[project.urls]`` in the file. You can use +any names inside it. Here it is for flit: + +.. code-block:: toml + + [project.urls] + Documentation = "https://flit.pypa.io" + Source = "https://github.com/pypa/flit" + +.. _pyproject_project_scripts: + +Scripts section +~~~~~~~~~~~~~~~ + +This section is called ``[project.scripts]`` in the file. +Each key and value describes a shell command to be installed along with +your package. These work like setuptools 'entry points'. Here's the section +for flit: + +.. code-block:: toml + + [project.scripts] + flit = "flit:main" + + +This will create a ``flit`` command, which will call the function ``main()`` +imported from :mod:`flit`. + +A similar table called ``[project.gui-scripts]`` defines commands which launch +a GUI. This only makes a difference on Windows, where GUI scripts are run +without a console. + +.. _pyproject_project_entrypoints: + +Entry points sections +~~~~~~~~~~~~~~~~~~~~~ + +You can declare `entry points `_ +using sections named :samp:`[project.entry-points.{groupname}]`. E.g. to +provide a pygments lexer from your package: + +.. code-block:: toml + + [project.entry-points."pygments.lexers"] + dogelang = "dogelang.lexer:DogeLexer" + +In each ``package:name`` value, the part before the colon should be an +importable module name, and the latter part should be the name of an object +accessible within that module. The details of what object to expose depend on +the application you're extending. + +If the group name contains a dot, it must be quoted (``"pygments.lexers"`` +above). Script entry points are defined in :ref:`scripts tables +`, so you can't use the group names +``console_scripts`` or ``gui_scripts`` here. + +.. _pyproject_module: + +Module section +~~~~~~~~~~~~~~ + +If your package will have different names for installation and import, +you should specify the install (PyPI) name in the ``[project]`` table +(:ref:`see above `), and the import name in a +``[tool.flit.module]`` table: + +.. code-block:: toml + + [project] + name = "pynsist" + # ... + + [tool.flit.module] + name = "nsist" + +Flit looks for the source of the package by its import name. The source may be +located either in the directory that holds the ``pyproject.toml`` file, or in a +``src/`` subdirectory. + +.. _pyproject_old_metadata: + +Old style metadata +------------------ + +Flit's older way to specify metadata is in a ``[tool.flit.metadata]`` table, +along with ``[tool.flit.scripts]`` and ``[tool.flit.entrypoints]``, described +below. This is still recognised for now, but you can't mix it with +:ref:`pyproject_toml_project`. + +There are three required fields: + +module + The name of the module/package, as you'd use in an import statement. +author + Your name +author-email + Your email address + +e.g. for flit itself + +.. code-block:: toml + + [tool.flit.metadata] + module = "flit" + author = "Thomas Kluyver" + author-email = "thomas@kluyver.me.uk" + +.. versionchanged:: 1.1 + + ``home-page`` was previously required. + +The remaining fields are optional: + +home-page + A URL for the project, such as its Github repository. +requires + A list of other packages from PyPI that this package needs. Each package may + be followed by a version specifier like ``(>=4.1)`` or ``>=4.1``, and/or an + `environment marker`_ + after a semicolon. For example: + + .. code-block:: toml + + requires = [ + "requests >=2.6", + "configparser; python_version == '2.7'", + ] + +requires-extra + Lists of packages needed for every optional feature. The requirements + are specified in the same format as for ``requires``. The requirements of + the two reserved extras ``test`` and ``doc`` as well as the extra ``dev`` + are installed by ``flit install``. For example: + + .. code-block:: toml + + [tool.flit.metadata.requires-extra] + test = [ + "pytest >=2.7.3", + "pytest-cov", + ] + doc = ["sphinx"] + + .. versionadded:: 1.1 + +description-file + A path (relative to the .toml file) to a file containing a longer description + of your package to show on PyPI. This should be written in `reStructuredText + `_, Markdown or + plain text, and the filename should have the appropriate extension + (``.rst``, ``.md`` or ``.txt``). +classifiers + A list of `Trove classifiers `_. + Add ``Private :: Do Not Upload`` into the list to prevent a private package + from uploading on PyPI by accident. +requires-python + A version specifier for the versions of Python this requires, e.g. ``~=3.3`` or + ``>=3.3,<4`` which are equivalents. +dist-name + If you want your package's name on PyPI to be different from the importable + module name, set this to the PyPI name. +keywords + Comma separated list of words to help with searching for your package. +license + The name of a license, if you're using one for which there isn't a Trove + classifier. It's recommended to use Trove classifiers instead of this in + most cases. +maintainer, maintainer-email + Like author, for if you've taken over a project from someone else. + +Here was the metadata section from flit using the older style: + +.. code-block:: toml + + [tool.flit.metadata] + module="flit" + author="Thomas Kluyver" + author-email="thomas@kluyver.me.uk" + home-page="https://github.com/pypa/flit" + requires=[ + "flit_core >=2.2.0", + "requests", + "docutils", + "tomli", + "tomli-w", + ] + requires-python=">=3.6" + description-file="README.rst" + classifiers=[ + "Intended Audience :: Developers", + "License :: OSI Approved :: BSD License", + "Programming Language :: Python :: 3", + "Topic :: Software Development :: Libraries :: Python Modules", + ] + +.. _pyproject_toml_urls: + +URLs subsection +~~~~~~~~~~~~~~~ + +Your project's page on `pypi.org `_ can show a number of +links, in addition to the ``home-page`` URL described above. You can +point people to documentation or a bug tracker, for example. + +This section is called ``[tool.flit.metadata.urls]`` in the file. You can use +any names inside it. Here it is for flit: + +.. code-block:: toml + + [tool.flit.metadata.urls] + Documentation = "https://flit.pypa.io" + +.. versionadded:: 1.0 + +.. _pyproject_toml_scripts: + +Scripts section +~~~~~~~~~~~~~~~ + +A ``[tool.flit.scripts]`` table can be used along with ``[tool.flit.metadata]``. +It is in the same format as the newer ``[project.scripts]`` table +:ref:`described above `. + +Entry points sections +~~~~~~~~~~~~~~~~~~~~~ + +``[tool.flit.entrypoints]`` tables can be used along with ``[tool.flit.metadata]``. +They are in the same format as the newer ``[project.entry-points]`` tables +:ref:`described above `. + +.. _pyproject_toml_sdist: + +Sdist section +------------- + +.. versionadded:: 2.0 + +When you use :ref:`build_cmd` or :ref:`publish_cmd`, Flit builds an sdist +(source distribution) tarball containing the files that are checked into version +control (git or mercurial). If you want more control, or it doesn't recognise +your version control system, you can give lists of paths or glob patterns as +``include`` and ``exclude`` in this section. For example: + +.. code-block:: toml + + [tool.flit.sdist] + include = ["doc/"] + exclude = ["doc/*.html"] + +These paths: + +- Always use ``/`` as a separator (POSIX style) +- Must be relative paths from the directory containing ``pyproject.toml`` +- Cannot go outside that directory (no ``../`` paths) +- Cannot contain control characters or ``<>:"\\`` +- Can refer to directories, in which case they include everything under the + directory, including subdirectories +- Should match the case of the files they refer to, as case-insensitive matching + is platform dependent + +.. versionchanged:: 3.8 + Include and exclude patterns can now use recursive glob patterns (``**``). + +Exclusions have priority over inclusions. Bytecode is excluded by default and cannot +be included. + +.. note:: + + If you are not using :ref:`build_cmd` but ``flit_core`` via another build + frontend, Flit doesn't doesn't check the VCS for files to include but instead + builds a 'minimal' sdist (which includes the files necessary to build a wheel). + You'll have to adapt your inclusion/exclusion rules to achieve the same result + as you'd get with :ref:`build_cmd`. + +.. _pyproject_toml_external_data: + +External data section +--------------------- + +.. versionadded:: 3.7 + +Data files which your code will use should go inside the Python package folder. +Flit will package these with no special configuration. + +However, sometimes it's useful to package external files for system integration, +such as man pages or files defining a Jupyter extension. To do this, arrange +the files within a directory such as ``data``, next to your ``pyproject.toml`` +file, and add a section like this: + +.. code-block:: toml + + [tool.flit.external-data] + directory = "data" + +Paths within this directory are typically installed to corresponding paths under +a prefix (such as a virtualenv directory). E.g. you might save a man page for a +script as ``(data)/share/man/man1/foo.1``. + +Whether these files are detected by the systems they're meant to integrate with +depends on how your package is installed and how those systems are configured. +For instance, installing in a virtualenv usually doesn't affect anything outside +that environment. Don't rely on these files being picked up unless you have +close control of how the package will be installed. + +If you install a package with ``flit install --symlink``, a symlink is made +for each file in the external data directory. Otherwise (including development +installs with ``pip install -e``), these files are copied to their destination, +so changes here won't take effect until you reinstall the package. + +.. note:: + + For users coming from setuptools: external data corresponds to setuptools' + ``data_files`` parameter, although setuptools offers more flexibility. + +.. _environment marker: https://www.python.org/dev/peps/pep-0508/#environment-markers 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 `, +a feature which some people care about. + +There have been many other efforts to improve the user experience of Python +packaging, such as `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 `_ and +`Enscons `_. + +Other options +------------- + +If your package needs a build step, you won't be able to use Flit. +`Setuptools `_ 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 +`_ have features which help add and update +dependencies on other packages. diff --git a/doc/reproducible.rst b/doc/reproducible.rst new file mode 100644 index 0000000..2894fc8 --- /dev/null +++ b/doc/reproducible.rst @@ -0,0 +1,34 @@ +Reproducible builds +=================== + +.. versionadded:: 0.8 + +Wheels built by flit are reproducible: if you build from the same source code, +you should be able to make wheels that are exactly identical, byte for byte. +This is useful for verifying software. For more details, see +`reproducible-builds.org `__. + +There is a caveat, however: wheels (which are zip files) include the +modification timestamp from each file. This will +probably be different on each computer, because it indicates when your local +copy of the file was written, not when it was changed in version control. +These timestamps can be overridden by the environment variable +:envvar:`SOURCE_DATE_EPOCH`. + +.. code-block:: shell + + SOURCE_DATE_EPOCH=$(date +%s) + flit publish + # Record the value of SOURCE_DATE_EPOCH in release notes for reproduction + +.. versionchanged:: 0.12 + Normalising permission bits + +Flit normalises the permission bits of files copied into a wheel to either +755 (executable) or 644. This means that a file is readable by all users +and writable only by the user who owns it. + +The most popular version control systems only track the executable bit, +so checking out the same repository on systems with different umasks +(e.g. Debian and Fedora) produces files with different permissions. With Flit +0.11 and earlier, this difference would produce non-identical wheels. diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..87126c9 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,3 @@ +sphinx ~= 4.2 +sphinxcontrib_github_alt ~= 1.2 +sphinx-rtd-theme ~= 1.0 diff --git a/doc/upload.rst b/doc/upload.rst new file mode 100644 index 0000000..df5af5e --- /dev/null +++ b/doc/upload.rst @@ -0,0 +1,77 @@ +Controlling package uploads +=========================== + +.. program:: flit publish + +The command ``flit publish`` will upload your package to a package index server. +The default settings let you upload to `PyPI `_, +the default Python Package Index, with a single user account. + +If you want to upload to other servers, or with more than one user account, +or upload packages from a continuous integration job, +you can configure Flit in two main ways: + +Using .pypirc +------------- + +You can create or edit a config file in your home directory, ``~/.pypirc`` that +will be used by default or you can specify a custom location. +This is also used by other Python tools such as `twine +`_. + +For instance, to upload a package to the `Test PyPI server `_ +instead of the normal PyPI, use a config file looking like this: + +.. code-block:: ini + + [distutils] + index-servers = + pypi + testpypi + + [pypi] + repository = https://upload.pypi.org/legacy/ + username = sirrobin # Replace with your PyPI username + + [testpypi] + repository = https://test.pypi.org/legacy/ + username = sirrobin # Replace with your TestPyPI username + +You can select an index server from this config file with the +:option:`--repository` option:: + + flit publish --repository testpypi + +If you don't use this option, +Flit will use the server called ``pypi`` in the config file. If that doesn't +exist, it uploads to PyPI at ``https://upload.pypi.org/legacy/`` by default. + +If you publish a package and you don't have a ``.pypirc`` file, Flit will create +it to store your username. + +Flit tries to store your password securely using the +`keyring `_ library. +If keyring is not installed, Flit will ask for your password for each upload. +Alternatively, you can also manually add your password to the ``.pypirc`` file +(``password = ...``) + +.. _upload_envvars: + +Using environment variables +--------------------------- + +You can specify a server to upload to with :envvar:`FLIT_INDEX_URL`, and +pass credentials with :envvar:`FLIT_USERNAME` and :envvar:`FLIT_PASSWORD`. +Environment variables take precedence over the config file, except if you use +the :option:`--repository` option to explicitly pick a server from the config file. + +This can make it easier to automate uploads, for example to release packages +from a continuous integration job. + +.. warning:: + + Storing a password in an environment variable is convenient, but it's + `easy to accidentally leak it `_. + Look out for scripts that helpfully print all environment variables for + debugging, and remember that other scripts and libraries you run in + that environment have access to your password. -- cgit v1.2.3