.\" Man page generated from reStructuredText.
.
.TH "FLIT" "1" "Nov 23, 2022" "3.8.0" "Flit"
.SH NAME
flit \- Flit Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
\fBFlit\fP is a simple way to put Python packages and modules on PyPI.
It tries to require less thought about packaging and help you avoid common
mistakes.
See \fI\%Why use Flit?\fP <\fBhttps://flit.readthedocs.io/en/latest/rationale.html\fP> for
more about how it compares to other Python packaging tools.
.SH INSTALL
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ python3 \-m pip install flit
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Flit requires Python 3 and therefore needs to be installed using the Python 3
version of pip.
.sp
Python 2 modules can be distributed using Flit, but need to be importable on
Python 3 without errors.
.SH USAGE
.sp
Say you\(aqre writing a module \fBfoobar\fP — either as a single file \fBfoobar.py\fP,
or as a directory — and you want to distribute it.
.INDENT 0.0
.IP 1. 3
Make sure that foobar\(aqs docstring starts with a one\-line summary of what
the module is, and that it has a \fB__version__\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
"""An amazing sample package!"""

__version__ = "0.1"
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Install flit if you don\(aqt already have it:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
python3 \-m pip install flit
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Run \fBflit init\fP in the directory containing the module to create a
\fBpyproject.toml\fP file. It will look something like this:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
[build\-system]
requires = ["flit_core >=3.2,<4"]
build\-backend = "flit_core.buildapi"

[project]
name = "foobar"
authors = [{name = "Sir Robin", email = "robin@camelot.uk"}]
dynamic = ["version", "description"]

[project.urls]
Home = "https://github.com/sirrobin/foobar"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can edit this file to add other metadata, for example to set up
command line scripts. See the
\fI\%pyproject.toml page\fP <\fBhttps://flit.readthedocs.io/en/latest/pyproject_toml.html#scripts-section\fP>
of the documentation.
.sp
If you have already got a \fBflit.ini\fP file to use with older versions of
Flit, convert it to \fBpyproject.toml\fP by running \fBpython3 \-m flit.tomlify\fP\&.
.IP 4. 3
Run this command to upload your code to PyPI:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
flit publish
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Once your package is published, people can install it using \fIpip\fP just like
any other package. In most cases, pip will download a \(aqwheel\(aq package, a
standard format it knows how to install. If you specifically ask pip to install
an \(aqsdist\(aq package, it will install and use Flit in a temporary environment.
.sp
To install a package locally for development, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
flit install [\-\-symlink] [\-\-python path/to/python]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Flit packages a single importable module or package at a time, using the import
name as the name on PyPI. All subpackages and data files within a package are
included automatically.
.SH DOCUMENTATION CONTENTS
.SS The pyproject.toml config file
.sp
This file lives next to the module or package.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Older version of Flit (up to 0.11) used a flit.ini file for
similar information. These files no longer work with Flit 3 and above.
.sp
Run \fBpython3 \-m flit.tomlify\fP to convert a \fBflit.ini\fP file to
\fBpyproject.toml\fP\&.
.UNINDENT
.UNINDENT
.SS Build system section
.sp
This tells tools like pip to build your project with flit. It\(aqs a standard
defined by PEP 517. For any new project using Flit, it will look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[build\-system]
requires = ["flit_core >=3.2,<4"]
build\-backend = "flit_core.buildapi"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Version constraints:
.INDENT 0.0
.IP \(bu 2
For now, all packages should specify \fB<4\fP, so they won\(aqt be impacted by
changes in the next major version.
.IP \(bu 2
\fI\%New style metadata\fP requires \fBflit_core >=3.2\fP
.IP \(bu 2
\fI\%Old style metadata\fP requires \fBflit_core >=2,<4\fP
.IP \(bu 2
The older flit.ini file requires \fBflit_core <3\fP\&.
.IP \(bu 2
TOML features new in version 1.0 require \fBflit_core >=3.4\fP\&.
.IP \(bu 2
\fBflit_core\fP 3.3 is the last version supporting Python 3.4 & 3.5. Packages
supporting these Python versions can only use \fI\%TOML v0.5\fP <\fBhttps://toml.io/en/v0.5.0\fP>\&.
.IP \(bu 2
Only \fBflit_core\fP 2.x can build packages on Python 2, so packages still
supporting Python 2 cannot use new\-style metadata (the \fB[project]\fP table).
.UNINDENT
.SS New style metadata
.sp
New in version 3.2.

.sp
The new standard way to specify project metadata is in a \fB[project]\fP table,
as defined by \fI\%PEP 621\fP <\fBhttps://www.python.org/dev/peps/pep-0621\fP>\&. Flit works for now with either this or the older
\fB[tool.flit.metadata]\fP table (\fI\%described below\fP),
but it won\(aqt allow you to mix them.
.sp
A simple \fB[project]\fP table might look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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"]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The allowed fields are:
.INDENT 0.0
.TP
.B 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 \fI\%Module section\fP if that needs to be
different).
.sp
Changed in version 3.8: Hyphens in the project name are now translated to underscores for the
import name.

.TP
.B version
Version number as a string. If you want Flit to get this from a
\fB__version__\fP attribute, leave it out of the TOML config and include
"version" in the \fBdynamic\fP field.
.TP
.B 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 \fBdynamic\fP field.
.TP
.B 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 \fI\%reStructuredText\fP <\fBhttp://docutils.sourceforge.net/docs/user/rst/quickref.html\fP>, Markdown or
plain text, and the filename should have the appropriate extension
(\fB\&.rst\fP, \fB\&.md\fP or \fB\&.txt\fP). Alternatively, \fBreadme\fP can be a table with
either a \fBfile\fP key (a relative path) or a \fBtext\fP key (literal text), and
an optional \fBcontent\-type\fP key (e.g. \fBtext/x\-rst\fP).
.TP
.B requires\-python
A version specifier for the versions of Python this requires, e.g. \fB~=3.3\fP or
\fB>=3.3,<4\fP, which are equivalents.
.TP
.B license
A table with either a \fBfile\fP key (a relative path to a license file) or a
\fBtext\fP key (the license text).
.TP
.B authors
A list of tables with \fBname\fP and \fBemail\fP keys (both optional) describing
the authors of the project.
.TP
.B maintainers
Same format as authors.
.TP
.B keywords
A list of words to help with searching for your package.
.TP
.B classifiers
A list of \fI\%Trove classifiers\fP <\fBhttps://pypi.python.org/pypi?%3Aaction=list_classifiers\fP>\&.
Add \fBPrivate :: Do Not Upload\fP into the list to prevent a private package
from being uploaded to PyPI by accident.
.TP
.B dependencies & optional\-dependencies
See \fI\%Dependencies\fP\&.
.TP
.B urls
See \fI\%URLs table\fP\&.
.TP
.B scripts & gui\-scripts
See \fI\%Scripts section\fP\&.
.TP
.B entry\-points
See \fI\%Entry points sections\fP\&.
.TP
.B dynamic
A list of field names which aren\(aqt specified here, for which Flit should
find a value at build time. Only "version" and "description" are accepted.
.UNINDENT
.SS Dependencies
.sp
The \fBdependencies\fP field is a list of other packages from PyPI that this
package needs. Each package may be followed by a version specifier like
\fB>=4.1\fP, and/or an \fI\%environment marker\fP <\fBhttps://www.python.org/dev/peps/pep-0508/#environment-markers\fP>
after a semicolon. For example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dependencies = [
    "requests >=2.6",
    "configparser; python_version == \(aq2.7\(aq",
]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fB[project.optional\-dependencies]\fP table contains lists of packages needed
for every optional feature. The requirements are specified in the same format as
for \fBdependencies\fP\&. For example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[project.optional\-dependencies]
test = [
    "pytest >=2.7.3",
    "pytest\-cov",
]
doc = ["sphinx"]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
You can call these optional features anything you want, although \fBtest\fP and
\fBdoc\fP are common ones. You specify them for installation in square brackets
after the package name or directory, e.g. \fBpip install \(aq.[test]\(aq\fP\&.
.SS URLs table
.sp
Your project\(aqs page on \fI\%pypi.org\fP <\fBhttps://pypi.org/\fP> can show a number of
links. You can point people to documentation or a bug tracker, for example.
.sp
This section is called \fB[project.urls]\fP in the file. You can use
any names inside it. Here it is for flit:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[project.urls]
Documentation = "https://flit.pypa.io"
Source = "https://github.com/pypa/flit"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Scripts section
.sp
This section is called \fB[project.scripts]\fP in the file.
Each key and value describes a shell command to be installed along with
your package. These work like setuptools \(aqentry points\(aq. Here\(aqs the section
for flit:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[project.scripts]
flit = "flit:main"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create a \fBflit\fP command, which will call the function \fBmain()\fP
imported from \fBflit\fP\&.
.sp
A similar table called \fB[project.gui\-scripts]\fP defines commands which launch
a GUI. This only makes a difference on Windows, where GUI scripts are run
without a console.
.SS Entry points sections
.sp
You can declare \fI\%entry points\fP <\fBhttp://entrypoints.readthedocs.io/en/latest/\fP>
using sections named \fB[project.entry\-points.\fP\fIgroupname\fP\fB]\fP\&. E.g. to
provide a pygments lexer from your package:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[project.entry\-points."pygments.lexers"]
dogelang = "dogelang.lexer:DogeLexer"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In each \fBpackage:name\fP 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\(aqre extending.
.sp
If the group name contains a dot, it must be quoted (\fB"pygments.lexers"\fP
above). Script entry points are defined in \fI\%scripts tables\fP, so you can\(aqt use the group names
\fBconsole_scripts\fP or \fBgui_scripts\fP here.
.SS Module section
.sp
If your package will have different names for installation and import,
you should specify the install (PyPI) name in the \fB[project]\fP table
(\fI\%see above\fP), and the import name in a
\fB[tool.flit.module]\fP table:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[project]
name = "pynsist"
# ...

[tool.flit.module]
name = "nsist"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Flit looks for the source of the package by its import name. The source may be
located either in the directory that holds the \fBpyproject.toml\fP file, or in a
\fBsrc/\fP subdirectory.
.SS Old style metadata
.sp
Flit\(aqs older way to specify metadata is in a \fB[tool.flit.metadata]\fP table,
along with \fB[tool.flit.scripts]\fP and \fB[tool.flit.entrypoints]\fP, described
below. This is still recognised for now, but you can\(aqt mix it with
\fI\%New style metadata\fP\&.
.sp
There are three required fields:
.INDENT 0.0
.TP
.B module
The name of the module/package, as you\(aqd use in an import statement.
.TP
.B author
Your name
.TP
.B author\-email
Your email address
.UNINDENT
.sp
e.g. for flit itself
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[tool.flit.metadata]
module = "flit"
author = "Thomas Kluyver"
author\-email = "thomas@kluyver.me.uk"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 1.1: \fBhome\-page\fP was previously required.

.sp
The remaining fields are optional:
.INDENT 0.0
.TP
.B home\-page
A URL for the project, such as its Github repository.
.TP
.B requires
A list of other packages from PyPI that this package needs. Each package may
be followed by a version specifier like \fB(>=4.1)\fP or \fB>=4.1\fP, and/or an
\fI\%environment marker\fP <\fBhttps://www.python.org/dev/peps/pep-0508/#environment-markers\fP>
after a semicolon. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
requires = [
    "requests >=2.6",
    "configparser; python_version == \(aq2.7\(aq",
]
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B requires\-extra
Lists of packages needed for every optional feature. The requirements
are specified in the same format as for \fBrequires\fP\&. The requirements of
the two reserved extras \fBtest\fP and \fBdoc\fP as well as the extra \fBdev\fP
are installed by \fBflit install\fP\&. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[tool.flit.metadata.requires\-extra]
test = [
    "pytest >=2.7.3",
    "pytest\-cov",
]
doc = ["sphinx"]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 1.1.

.TP
.B 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 \fI\%reStructuredText\fP <\fBhttp://docutils.sourceforge.net/docs/user/rst/quickref.html\fP>, Markdown or
plain text, and the filename should have the appropriate extension
(\fB\&.rst\fP, \fB\&.md\fP or \fB\&.txt\fP).
.TP
.B classifiers
A list of \fI\%Trove classifiers\fP <\fBhttps://pypi.python.org/pypi?%3Aaction=list_classifiers\fP>\&.
Add \fBPrivate :: Do Not Upload\fP into the list to prevent a private package
from uploading on PyPI by accident.
.TP
.B requires\-python
A version specifier for the versions of Python this requires, e.g. \fB~=3.3\fP or
\fB>=3.3,<4\fP which are equivalents.
.TP
.B dist\-name
If you want your package\(aqs name on PyPI to be different from the importable
module name, set this to the PyPI name.
.TP
.B keywords
Comma separated list of words to help with searching for your package.
.TP
.B license
The name of a license, if you\(aqre using one for which there isn\(aqt a Trove
classifier. It\(aqs recommended to use Trove classifiers instead of this in
most cases.
.TP
.B maintainer, maintainer\-email
Like author, for if you\(aqve taken over a project from someone else.
.UNINDENT
.sp
Here was the metadata section from flit using the older style:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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",
]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS URLs subsection
.sp
Your project\(aqs page on \fI\%pypi.org\fP <\fBhttps://pypi.org/\fP> can show a number of
links, in addition to the \fBhome\-page\fP URL described above. You can
point people to documentation or a bug tracker, for example.
.sp
This section is called \fB[tool.flit.metadata.urls]\fP in the file. You can use
any names inside it. Here it is for flit:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[tool.flit.metadata.urls]
Documentation = "https://flit.pypa.io"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 1.0.

.SS Scripts section
.sp
A \fB[tool.flit.scripts]\fP table can be used along with \fB[tool.flit.metadata]\fP\&.
It is in the same format as the newer \fB[project.scripts]\fP table
\fI\%described above\fP\&.
.SS Entry points sections
.sp
\fB[tool.flit.entrypoints]\fP tables can be used along with \fB[tool.flit.metadata]\fP\&.
They are in the same format as the newer \fB[project.entry\-points]\fP tables
\fI\%described above\fP\&.
.SS Sdist section
.sp
New in version 2.0.

.sp
When you use build_cmd or 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\(aqt recognise
your version control system, you can give lists of paths or glob patterns as
\fBinclude\fP and \fBexclude\fP in this section. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[tool.flit.sdist]
include = ["doc/"]
exclude = ["doc/*.html"]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These paths:
.INDENT 0.0
.IP \(bu 2
Always use \fB/\fP as a separator (POSIX style)
.IP \(bu 2
Must be relative paths from the directory containing \fBpyproject.toml\fP
.IP \(bu 2
Cannot go outside that directory (no \fB\&../\fP paths)
.IP \(bu 2
Cannot contain control characters or \fB<>:"\e\e\fP
.IP \(bu 2
Can refer to directories, in which case they include everything under the
directory, including subdirectories
.IP \(bu 2
Should match the case of the files they refer to, as case\-insensitive matching
is platform dependent
.UNINDENT
.sp
Changed in version 3.8: Include and exclude patterns can now use recursive glob patterns (\fB**\fP).

.sp
Exclusions have priority over inclusions. Bytecode is excluded by default and cannot
be included.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you are not using build_cmd but  \fBflit_core\fP via another build
frontend, Flit doesn\(aqt doesn\(aqt check the VCS for files to include but instead
builds a \(aqminimal\(aq sdist (which includes the files necessary to build a wheel).
You\(aqll have to adapt your inclusion/exclusion rules to achieve the same result
as you\(aqd get with build_cmd\&.
.UNINDENT
.UNINDENT
.SS External data section
.sp
New in version 3.7.

.sp
Data files which your code will use should go inside the Python package folder.
Flit will package these with no special configuration.
.sp
However, sometimes it\(aqs 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 \fBdata\fP, next to your \fBpyproject.toml\fP
file, and add a section like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[tool.flit.external\-data]
directory = "data"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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 \fB(data)/share/man/man1/foo.1\fP\&.
.sp
Whether these files are detected by the systems they\(aqre 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\(aqt affect anything outside
that environment. Don\(aqt rely on these files being picked up unless you have
close control of how the package will be installed.
.sp
If you install a package with \fBflit install \-\-symlink\fP, a symlink is made
for each file in the external data directory. Otherwise (including development
installs with \fBpip install \-e\fP), these files are copied to their destination,
so changes here won\(aqt take effect until you reinstall the package.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For users coming from setuptools: external data corresponds to setuptools\(aq
\fBdata_files\fP parameter, although setuptools offers more flexibility.
.UNINDENT
.UNINDENT
.SS Flit command line interface
.sp
All operations use the \fBflit\fP command, followed by one of a number of
subcommands.
.SS Common options
.INDENT 0.0
.TP
.B \-f <path>, \-\-ini\-file <path>
Path to a config file specifying the module to build. The default is
\fBpyproject.toml\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Show the version of Flit in use.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-help
Show help on the command\-line interface.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-debug
Show more detailed logs about what flit is doing.
.UNINDENT
.SS \fBflit build\fP
.sp
Build a wheel and an sdist (tarball) from the package.
.INDENT 0.0
.TP
.B \-\-format <format>
Limit to building either \fBwheel\fP or \fBsdist\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-setup\-py
Generate a \fBsetup.py\fP file in the sdist, so it can be installed by older
versions of pip.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-setup\-py
Don\(aqt 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.
.sp
Changed in version 3.5: Generating \fBsetup.py\fP disabled by default.

.UNINDENT
.SS \fBflit publish\fP
.sp
Build a wheel and an sdist (tarball) from the package, and upload them to PyPI
or another repository.
.INDENT 0.0
.TP
.B \-\-format <format>
Limit to publishing either \fBwheel\fP or \fBsdist\fP\&.
You should normally publish the two formats together.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-setup\-py
Generate a \fBsetup.py\fP file in the sdist, so it can be installed by older
versions of pip.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-setup\-py
Don\(aqt 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.
.sp
Changed in version 3.5: Generating \fBsetup.py\fP disabled by default.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-repository <repository>
Name of a repository to upload packages to. Should match a section in
\fB~/.pypirc\fP\&. The default is \fBpypi\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pypirc <pypirc>
The .pypirc config file to be used. The default is \fB~/.pypirc\fP\&.
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
upload
.UNINDENT
.UNINDENT
.SS \fBflit install\fP
.sp
Install the package on your system.
.sp
By default, the package is installed to the same Python environment that Flit
itself is installed in; use \fI\%\-\-python\fP or \fI\%FLIT_INSTALL_PYTHON\fP
to override this.
.sp
If you don\(aqt have permission to modify the environment (e.g. the system Python
on Linux), Flit may do a user install instead. Use the \fI\%\-\-user\fP or
\fI\%\-\-env\fP flags to force this one way or the other, rather than letting
Flit guess.
.INDENT 0.0
.TP
.B \-s, \-\-symlink
Symlink the module into site\-packages rather than copying it, so that you
can test changes without reinstalling the module.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pth\-file
Create a \fB\&.pth\fP file in site\-packages rather than copying the module, so
you can test changes without reinstalling. This is a less elegant alternative
to \fB\-\-symlink\fP, but it works on Windows, which typically doesn\(aqt allow
symlinks.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-deps <dependency option>
Which dependencies to install. One of \fBall\fP, \fBproduction\fP, \fBdevelop\fP,
or \fBnone\fP\&. \fBall\fP and \fBdevelop\fP install the extras \fBtest\fP, \fBdoc\fP,
and \fBdev\fP\&. Default \fBall\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-extras <extra[,extra,...]>
Which named extra features to install dependencies for. Specify \fBall\fP to
install all optional dependencies, or a comma\-separated list of extras.
Default depends on \fB\-\-deps\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-only\-deps
Install the dependencies of this package, but not the package itself.
.sp
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.
.sp
New in version 3.8.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-user
Do a user\-local installation. This is the default if flit is not in a
virtualenv or conda env (if the environment\(aqs library directory is
read\-only and \fBsite.ENABLE_USER_SITE\fP is true).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-env
Install into the environment \- the opposite of \fI\%\-\-user\fP\&.
This is the default in a virtualenv or conda env (if the environment\(aqs
library directory is writable or \fBsite.ENABLE_USER_SITE\fP is false).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-python <path to 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 \fI\%FLIT_INSTALL_PYTHON\fP if this option is not given.
.sp
Changed in version 2.1: Added \fI\%FLIT_INSTALL_PYTHON\fP and use its value over the Python
running Flit when an explicit \fI\%\-\-python\fP option is not given.

.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Flit calls pip to do the installation. You can set any of pip\(aqs options
\fI\%using its environment variables\fP <\fBhttps://pip.pypa.io/en/stable/topics/configuration/#environment-variables\fP>\&.
.sp
When you use the \fI\%\-\-symlink\fP or \fI\%\-\-pth\-file\fP options, pip
is used to install dependencies. Otherwise, Flit builds a wheel and then
calls pip to install that.
.UNINDENT
.UNINDENT
.SS \fBflit init\fP
.sp
Create a new \fBpyproject.toml\fP  config file by prompting for information about
the module in the current directory.
.SS Environment variables
.INDENT 0.0
.TP
.B FLIT_NO_NETWORK
New in version 0.10.

.sp
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\(aqs up to you to
ensure any necessary dependencies are installed.
.UNINDENT
.INDENT 0.0
.TP
.B FLIT_ROOT_INSTALL
By default, \fBflit install\fP 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.
.UNINDENT
.INDENT 0.0
.TP
.B FLIT_USERNAME
.TP
.B FLIT_PASSWORD
.TP
.B FLIT_INDEX_URL
New in version 0.11.

.sp
Set a username, password, and index URL for uploading packages.
See uploading packages with environment variables
for more information.
.sp
Token\-based upload to PyPI is supported. To upload using a PyPI token,
set \fBFLIT_USERNAME\fP to \fB__token__\fP, and \fBFLIT_PASSWORD\fP to the
token value.
.UNINDENT
.INDENT 0.0
.TP
.B FLIT_ALLOW_INVALID
New in version 0.13.

.sp
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\(aqt cause Flit to stop.
.sp
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 \fI\%open an issue\fP <\fBhttps://github.com/pypa/flit/issues\fP>\&.
.UNINDENT
.INDENT 0.0
.TP
.B FLIT_INSTALL_PYTHON
New in version 2.1.

.sp
Set a default Python interpreter for \fI\%flit install\fP to use when
\fI\%\-\-python\fP is not specified. The value can be either an absolute
path, or a command name (which will be found in \fBPATH\fP). If this is unset
or empty, the module is installed for the copy of Python that is running
Flit.
.UNINDENT
.INDENT 0.0
.TP
.B 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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
date +%s
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%The SOURCE_DATE_EPOCH specification\fP <\fBhttps://reproducible-builds.org/specs/source-date-epoch/\fP>
.UNINDENT
.UNINDENT
.UNINDENT
.SS Controlling package uploads
.sp
The command \fBflit publish\fP will upload your package to a package index server.
The default settings let you upload to \fI\%PyPI\fP <\fBhttps://pypi.org/\fP>,
the default Python Package Index, with a single user account.
.sp
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:
.SS Using .pypirc
.sp
You can create or edit a config file in your home directory, \fB~/.pypirc\fP that
will be used by default or you can specify a custom location.
This is also used by other Python tools such as \fI\%twine\fP <\fBhttps://pypi.python.org/pypi/twine\fP>\&.
.sp
For instance, to upload a package to the \fI\%Test PyPI server\fP <\fBhttps://test.pypi.org/\fP>
instead of the normal PyPI, use a config file looking like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can select an index server from this config file with the
\fB\-\-repository\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
flit publish \-\-repository testpypi
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you don\(aqt use this option,
Flit will use the server called \fBpypi\fP in the config file. If that doesn\(aqt
exist, it uploads to PyPI at \fBhttps://upload.pypi.org/legacy/\fP by default.
.sp
If you publish a package and you don\(aqt have a \fB\&.pypirc\fP file, Flit will create
it to store your username.
.sp
Flit tries to store your password securely using the
\fI\%keyring\fP <\fBhttps://pypi.python.org/pypi/keyring\fP> 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 \fB\&.pypirc\fP file
(\fBpassword = ...\fP)
.SS Using environment variables
.sp
You can specify a server to upload to with \fBFLIT_INDEX_URL\fP, and
pass credentials with \fBFLIT_USERNAME\fP and \fBFLIT_PASSWORD\fP\&.
Environment variables take precedence over the config file, except if you use
the \fB\-\-repository\fP option to explicitly pick a server from the config file.
.sp
This can make it easier to automate uploads, for example to release packages
from a continuous integration job.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Storing a password in an environment variable is convenient, but it\(aqs
\fI\%easy to accidentally leak it\fP <\fBhttps://www.diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/\fP>\&.
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.
.UNINDENT
.UNINDENT
.SS Reproducible builds
.sp
New in version 0.8.

.sp
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
\fI\%reproducible\-builds.org\fP <\fBhttps://reproducible-builds.org/\fP>\&.
.sp
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
\fBSOURCE_DATE_EPOCH\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
SOURCE_DATE_EPOCH=$(date +%s)
flit publish
# Record the value of SOURCE_DATE_EPOCH in release notes for reproduction
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 0.12: Normalising permission bits

.sp
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.
.sp
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.
.SS Why use Flit?
.sp
\fIMake the easy things easy and the hard things possible\fP is an old motto from
the Perl community. Flit is entirely focused on the \fIeasy things\fP part of that,
and leaves the hard things up to other tools.
.sp
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.
.sp
It\(aqs 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\(aqs 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\(aqt need to know about most of that.
.sp
What, specifically, does Flit make easy?
.INDENT 0.0
.IP \(bu 2
\fBflit init\fP helps you set up the information Flit needs about your
package.
.IP \(bu 2
Subpackages are automatically included: you only need to specify the
top\-level package.
.IP \(bu 2
Data files within a package directory are automatically included.
Missing data files has been a common packaging mistake with other tools.
.IP \(bu 2
The version number is taken from your package\(aqs \fB__version__\fP attribute,
so that always matches the version that tools like pip see.
.IP \(bu 2
\fBflit publish\fP uploads a package to PyPI, so you don\(aqt need a separate tool
to do this.
.UNINDENT
.sp
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.
.sp
Flit also has some support for reproducible builds,
a feature which some people care about.
.sp
There have been many other efforts to improve the user experience of Python
packaging, such as \fI\%pbr\fP <\fBhttps://pypi.org/project/pbr/\fP>, but before Flit,
these tended to build on setuptools and distutils. That was a pragmatic
decision, but it\(aqs hard to build something radically different on top of those
libraries. The existence of Flit spurred the development of new standards,
like \fI\%PEP 518\fP <\fBhttps://www.python.org/dev/peps/pep-0518\fP> and \fI\%PEP 517\fP <\fBhttps://www.python.org/dev/peps/pep-0517\fP>, which are now used by other packaging tools
such as \fI\%Poetry\fP <\fBhttps://python-poetry.org/\fP> and
\fI\%Enscons\fP <\fBhttps://pypi.org/project/enscons/\fP>\&.
.SS Other options
.sp
If your package needs a build step, you won\(aqt be able to use Flit.
\fI\%Setuptools\fP <\fBhttps://setuptools.readthedocs.io/en/latest/\fP> is the de\-facto
standard, but newer tools such as \fI\%Enscons\fP <\fBhttps://pypi.org/project/enscons/\fP> also cover this case.
.sp
Flit also doesn\(aqt help you manage dependencies: you have to add them to
\fBpyproject.toml\fP by hand. Tools like \fI\%Poetry\fP <\fBhttps://python-poetry.org/\fP> and \fI\%Pipenv\fP <\fBhttps://pypi.org/project/pipenv/\fP> have features which help add and update
dependencies on other packages.
.SS Bootstrapping
.sp
Flit is itself packaged using Flit, as are some foundational packaging tools
such as \fBpep517\fP\&. So where can you start if you need to install everything
from source?
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For most users, \fBpip\fP handles all this automatically. You should only need
to deal with this if you\(aqre building things entirely from scratch, such as
putting Python packages into another package format.
.UNINDENT
.UNINDENT
.sp
The key piece is \fBflit_core\fP\&. 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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-m flit_core.wheel
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And then you can install this wheel with the \fBbootstrap_install.py\fP script
included in the sdist (or by unzipping it to the correct directory):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# 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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As of version 3.6, flit_core bundles the \fBtomli\fP 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.
.sp
After \fBflit_core\fP, I recommend that you get \fI\%installer\fP <\fBhttps://pypi.org/project/installer/\fP> set up. You can use
\fBpython \-m flit_core.wheel\fP again to make a wheel, and then use installer
itself (from the source directory) to install it.
.sp
After that, you probably want to get \fI\%build\fP <\fBhttps://pypi.org/project/build/\fP>
and its dependencies installed as the goal of the bootstrapping phase. You can
then use \fBbuild\fP to create wheels of any other Python packages, and
\fBinstaller\fP to install them.
.SS Developing Flit
.sp
To get a development installation of Flit itself:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone https://github.com/pypa/flit.git
cd flit
python3 \-m pip install docutils requests
python3 bootstrap_dev.py
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This links Flit into the current Python environment, so you can make changes
and try them without having to reinstall each time.
.SS Testing
.sp
To run the tests in separate environments for each available Python version:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fI\%tox\fP <\fBhttps://tox.readthedocs.io/en/latest/\fP> has many options.
.sp
To run the tests in your current environment, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pytest
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Release history
.SS Version 3.8
.INDENT 0.0
.IP \(bu 2
A project name containing hyphens is now automatically translated to use
underscores for the import name (
.nf
:ghpull:\(ga566\(ga
.fi
).
.IP \(bu 2
New option \fBflit install \-\-only\-deps\fP to install the dependencies of
the package, but not the package itself.
.IP \(bu 2
Add support for recursive globbing (\fB**\fP) in sdist includes and excludes
(
.nf
:ghpull:\(ga550\(ga
.fi
).
.IP \(bu 2
Python\(aqs bytecode cache files (\fB__pycache__\fP folders and \fB\&.pyc\fP files)
are now always excluded from sdists (
.nf
:ghpull:\(ga581\(ga
.fi
).
.IP \(bu 2
Use tomllib in Python 3.11, rather than tomli (
.nf
:ghpull:\(ga573\(ga
.fi
, 
.nf
:ghpull:\(ga604\(ga
.fi
).
.IP \(bu 2
Fix crash when unable to get a password from \fBkeyring\fP (
.nf
:ghpull:\(ga567\(ga
.fi
).
.IP \(bu 2
Fix including modified files in sdist when using Mercurial (
.nf
:ghpull:\(ga541\(ga
.fi
).
.IP \(bu 2
Fix for some cases of determining whether a package supports Python 2 or not
(
.nf
:ghpull:\(ga593\(ga
.fi
).
.IP \(bu 2
Fix parsing version number from code using multiple assignments (
.nf
:ghpull:\(ga474\(ga
.fi
).
.IP \(bu 2
Document how to use a PyPI token with \fBFLIT_PASSWORD\fP (
.nf
:ghpull:\(ga602\(ga
.fi
).
.IP \(bu 2
Fix link to information about environment variables for pip (
.nf
:ghpull:\(ga576\(ga
.fi
).
.IP \(bu 2
Link to the docs for the latest stable version in package metadata
(
.nf
:ghpull:\(ga589\(ga
.fi
).
.IP \(bu 2
Remove a mention of the \fBtoml\fP package, which is no longer needed, from the
development page (
.nf
:ghpull:\(ga601\(ga
.fi
).
.IP \(bu 2
The bootstrap install script for \fBflit_core\fP accepts a
new \fB\-\-install\-root\fP option.
.IP \(bu 2
Ensure the license file is included in packages on PyPI (
.nf
:ghpull:\(ga603\(ga
.fi
).
.UNINDENT
.SS Version 3.7.1
.INDENT 0.0
.IP \(bu 2
Fix building packages which need execution to get the version number,
and have a relative import in \fB__init__.py\fP (
.nf
:ghpull:\(ga531\(ga
.fi
).
.UNINDENT
.SS Version 3.7
.INDENT 0.0
.IP \(bu 2
Support for external data files such
as man pages or Jupyter extension support files (
.nf
:ghpull:\(ga510\(ga
.fi
).
.IP \(bu 2
Project names are now lowercase in wheel filenames and \fB\&.dist\-info\fP folder
names, in line with the specifications (
.nf
:ghpull:\(ga498\(ga
.fi
).
.IP \(bu 2
Improved support for bootstrapping a Python environment,
e.g. for downstream packagers (
.nf
:ghpull:\(ga511\(ga
.fi
). \fBflit_core.wheel\fP is usable
with \fBpython \-m\fP to create wheels before the \fI\%build\fP <\fBhttps://pypi.org/project/build/\fP>
tool is available, and \fBflit_core\fP sdists also include a script to install
itself from a wheel before \fI\%installer\fP <\fBhttps://pypi.org/project/installer/\fP>
is available.
.IP \(bu 2
Use newer importlib APIs, fixing some deprecation warnings (
.nf
:ghpull:\(ga499\(ga
.fi
).
.UNINDENT
.SS Version 3.6
.INDENT 0.0
.IP \(bu 2
\fBflit_core\fP now bundles the \fI\%tomli\fP <\fBhttps://pypi.org/project/tomli/\fP> TOML
parser library (version 1.2.3) to avoid a circular dependency between
\fBflit_core\fP and \fBtomli\fP (
.nf
:ghpull:\(ga492\(ga
.fi
). This means \fBflit_core\fP now has
no dependencies except Python itself, both at build time and at runtime,
simplifying bootstrapping\&.
.UNINDENT
.SS Version 3.5.1
.INDENT 0.0
.IP \(bu 2
Fix development installs with \fBflit install \-\-symlink\fP and \fB\-\-pth\-file\fP,
which were broken in 3.5.0, especially for packages using a \fBsrc\fP folder
(
.nf
:ghpull:\(ga472\(ga
.fi
).
.UNINDENT
.SS Version 3.5
.INDENT 0.0
.IP \(bu 2
You can now use Flit to distribute a module or package inside a namespace
package (as defined by \fI\%PEP 420\fP <\fBhttps://www.python.org/dev/peps/pep-0420\fP>). To do this, specify the import name of the
concrete, inner module you are packaging \- e.g. \fBname = "sphinxcontrib.foo"\fP
\- either in the \fB[project]\fP table, or under \fB[tool.flit.module]\fP if you
want to use a different name on PyPI (
.nf
:ghpull:\(ga468\(ga
.fi
).
.IP \(bu 2
Flit no longer generates a \fBsetup.py\fP file in sdists (\fB\&.tar.gz\fP packages)
by default (
.nf
:ghpull:\(ga462\(ga
.fi
). Modern packaging tools don\(aqt need this. You can
use the \fB\-\-setup\-py\fP flag to keep adding it for now, but this will probably
be removed at some point in the future.
.IP \(bu 2
Fixed how \fBflit init\fP handles authors\(aq names with non\-ASCII characters
(
.nf
:ghpull:\(ga460\(ga
.fi
).
.IP \(bu 2
When \fBflit init\fP generates a LICENSE file, the new \fBpyproject.toml\fP now
references it (
.nf
:ghpull:\(ga467\(ga
.fi
).
.UNINDENT
.SS Version 3.4
.INDENT 0.0
.IP \(bu 2
Python 3.6 or above is now required, both for \fBflit\fP and \fBflit_core\fP\&.
.IP \(bu 2
Add a \fB\-\-setup\-py\fP option to \fBflit build\fP and \fBflit publish\fP, and a
warning when neither this nor \fB\-\-no\-setup\-py\fP are specified (
.nf
:ghpull:\(ga431\(ga
.fi
).
A future version will stop generating \fBsetup.py\fP files in sdists by default.
.IP \(bu 2
Add support for standardised editable installs \- \fBpip install \-e\fP \-
according to \fI\%PEP 660\fP <\fBhttps://www.python.org/dev/peps/pep-0660\fP> (
.nf
:ghpull:\(ga400\(ga
.fi
).
.IP \(bu 2
Add a \fB\-\-pypirc\fP option for \fBflit publish\fP to specify an alternative path
to a \fB\&.pypirc\fP config file describing package indexes (
.nf
:ghpull:\(ga434\(ga
.fi
).
.IP \(bu 2
Fix installing dependencies specified in a \fB[project]\fP table (
.nf
:ghpull:\(ga433\(ga
.fi
).
.IP \(bu 2
Fix building wheels when \fBSOURCE_DATE_EPOCH\fP (see reproducible) is
set to a date before 1980 (
.nf
:ghpull:\(ga448\(ga
.fi
).
.IP \(bu 2
Switch to using the \fI\%tomli\fP <\fBhttps://pypi.org/project/tomli/\fP> TOML parser,
in common with other packaging projects (
.nf
:ghpull:\(ga438\(ga
.fi
).
This supports TOML version 1.0.
.IP \(bu 2
Add a document on bootstrap (
.nf
:ghpull:\(ga441\(ga
.fi
).
.UNINDENT
.SS Version 3.3
.INDENT 0.0
.IP \(bu 2
\fBPKG\-INFO\fP files in sdists are now generated the same way as \fBMETADATA\fP in
wheels, fixing some issues with sdists (
.nf
:ghpull:\(ga410\(ga
.fi
).
.IP \(bu 2
\fBflit publish\fP now sends SHA\-256 hashes, fixing uploads to GitLab package
repositories (
.nf
:ghpull:\(ga416\(ga
.fi
).
.IP \(bu 2
The \fB[project]\fP metadata table from \fI\%PEP 621\fP <\fBhttps://www.python.org/dev/peps/pep-0621\fP> is now fully supported and
documented\&. Projects using this can now
specify \fBrequires = ["flit_core >=3.2,<4"]\fP in the \fB[build\-system]\fP table.
.UNINDENT
.SS Version 3.2
.INDENT 0.0
.IP \(bu 2
Experimental support for specifying metadata in a \fB[project]\fP table in
\fBpyproject.toml\fP as specified by \fI\%PEP 621\fP <\fBhttps://www.python.org/dev/peps/pep-0621\fP> (
.nf
:ghpull:\(ga393\(ga
.fi
). If you try
using this, please specify \fBrequires = ["flit_core >=3.2.0,<3.3"]\fP in the
\fB[build\-system]\fP table for now, in case it needs to change for the next
release.
.IP \(bu 2
Fix writing METADATA file with multi\-line information in certain fields
such as \fBAuthor\fP (
.nf
:ghpull:\(ga402\(ga
.fi
).
.IP \(bu 2
Fix building wheel when a directory such as LICENSES appears in the project
root directory (
.nf
:ghpull:\(ga401\(ga
.fi
).
.UNINDENT
.SS Version 3.1
.INDENT 0.0
.IP \(bu 2
Update handling of names & version numbers in wheel filenames and
\fB\&.dist\-info\fP folders in line with changes in the specs (
.nf
:ghpull:\(ga395\(ga
.fi
).
.IP \(bu 2
Switch from the deprecated \fBpytoml\fP package to \fBtoml\fP (
.nf
:ghpull:\(ga378\(ga
.fi
).
.IP \(bu 2
Fix specifying backend\-path in \fBpyproject.toml\fP for flit\-core (as a list
instead of a string).
.UNINDENT
.SS Version 3.0
.sp
Breaking changes:
.INDENT 0.0
.IP \(bu 2
Projects must now provide Flit with information in \fBpyproject.toml\fP files,
not the older \fBflit.ini\fP format (
.nf
:ghpull:\(ga338\(ga
.fi
).
.IP \(bu 2
\fBflit_core\fP once again requires Python 3 (>=3.4). Packages that support
Python 2 can still be built by \fBflit_core\fP 2.x, but can\(aqt rely on new
features (
.nf
:ghpull:\(ga342\(ga
.fi
).
.IP \(bu 2
The deprecated \fBflit installfrom\fP command was removed (
.nf
:ghpull:\(ga334\(ga
.fi
).
You can use \fBpip install git+https://github.com/...\fP instead.
.UNINDENT
.sp
Features and fixes:
.INDENT 0.0
.IP \(bu 2
Fix building sdists from a git repository with non\-ASCII characters in
filenames (
.nf
:ghpull:\(ga346\(ga
.fi
).
.IP \(bu 2
Fix identifying the version number when the code contains a subscript
assignment before \fB__version__ =\fP (
.nf
:ghpull:\(ga348\(ga
.fi
).
.IP \(bu 2
Script entry points can now use a class method (
.nf
:ghpull:\(ga359\(ga
.fi
).
.IP \(bu 2
Set suitable permission bits on metadata files in wheels (
.nf
:ghpull:\(ga256\(ga
.fi
).
.IP \(bu 2
Fixed line endings in the \fBRECORD\fP file when installing on Windows
(
.nf
:ghpull:\(ga368\(ga
.fi
).
.IP \(bu 2
Support for recording the source of local installations, as in \fI\%PEP 610\fP <\fBhttps://www.python.org/dev/peps/pep-0610\fP>
(
.nf
:ghpull:\(ga335\(ga
.fi
).
.IP \(bu 2
\fBflit init\fP will check for a README in the root of the project and
automatically set it as \fBdescription\-file\fP (
.nf
:ghpull:\(ga337\(ga
.fi
).
.IP \(bu 2
Pygments is not required for checking reStructuredText READMEs (
.nf
:ghpull:\(ga357\(ga
.fi
).
.IP \(bu 2
Packages where the version number can be recognised without executing their
code don\(aqt need their dependencies installed to build, which should make them
build faster (
.nf
:ghpull:\(ga361\(ga
.fi
).
.IP \(bu 2
Ensure the installed \fBRECORD\fP file is predictably ordered (
.nf
:ghpull:\(ga366\(ga
.fi
).
.UNINDENT
.SS Version 2.3
.INDENT 0.0
.IP \(bu 2
New projects created with init_cmd now declare that they require
\fBflit_core >=2,<4\fP (
.nf
:ghpull:\(ga328\(ga
.fi
). Any projects using \fBpyproject.toml\fP
(not \fBflit.ini\fP) should be compatible with flit 3.x.
.IP \(bu 2
Fix selecting files from a git submodule to include in an sdist
(
.nf
:ghpull:\(ga324\(ga
.fi
).
.IP \(bu 2
Fix checking classifiers when no writeable cache directory is available
(
.nf
:ghpull:\(ga319\(ga
.fi
).
.IP \(bu 2
Better errors when trying to install to a mis\-spelled or missing Python
interpreter (
.nf
:ghpull:\(ga331\(ga
.fi
).
.IP \(bu 2
Fix specifying \fB\-\-repository\fP before \fBupload\fP (
.nf
:ghpull:\(ga322\(ga
.fi
). Passing the
option like this is deprecated, and you should now pass it after \fBupload\fP\&.
.IP \(bu 2
Documentation improvements (
.nf
:ghpull:\(ga327\(ga
.fi
, 
.nf
:ghpull:\(ga318\(ga
.fi
, 
.nf
:ghpull:\(ga314\(ga
.fi
)
.UNINDENT
.SS Version 2.2
.INDENT 0.0
.IP \(bu 2
Allow underscores in package names with Python 2 (
.nf
:ghpull:\(ga305\(ga
.fi
).
.IP \(bu 2
Add a \fB\-\-no\-setup\-py\fP option to build sdists without a backwards\-compatible
\fBsetup.py\fP file (
.nf
:ghpull:\(ga311\(ga
.fi
).
.IP \(bu 2
Fix the generated \fBsetup.py\fP file for packages using a \fBsrc/\fP layout
(
.nf
:ghpull:\(ga303\(ga
.fi
).
.IP \(bu 2
Fix detecting when more than one file matches the module name specified
(
.nf
:ghpull:\(ga307\(ga
.fi
).
.IP \(bu 2
Fix installing to a venv on Windows with the \fB\-\-python\fP option
(
.nf
:ghpull:\(ga300\(ga
.fi
).
.IP \(bu 2
Don\(aqt echo the command in scripts installed with \fB\-\-symlink\fP or
\fB\-\-pth\-file\fP on Windows (
.nf
:ghpull:\(ga310\(ga
.fi
).
.IP \(bu 2
New \fBbootstrap_dev.py\fP script to set up a development installation of Flit
from the repository (
.nf
:ghpull:\(ga301\(ga
.fi
, 
.nf
:ghpull:\(ga306\(ga
.fi
).
.UNINDENT
.SS Version 2.1
.INDENT 0.0
.IP \(bu 2
Use compression when adding files to wheels.
.IP \(bu 2
Added the \fBFLIT_INSTALL_PYTHON\fP environment variable (
.nf
:ghpull:\(ga295\(ga
.fi
),
to configure flit to always install into a Python other than the one it\(aqs
running on.
.IP \(bu 2
\fBflit_core\fP uses the \fBintreehooks\fP shim package to load its bootstrapping
backend, until a released version of pip supports the standard
\fBbackend\-path\fP mechanism.
.UNINDENT
.SS Version 2.0
.sp
Flit 2 is a major architecture change. The \fBflit_core\fP package now provides
a \fI\%PEP 517\fP <\fBhttps://www.python.org/dev/peps/pep-0517\fP> backend for building packages, while \fBflit\fP is a
command line interface extending that.
.sp
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 \fBflit\fP command requires Python 3.5 or above.
You will need to change the build\-system table in your \fBpyproject.toml\fP file
to look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[build\-system]
requires = ["flit_core >=2,<4"]
build\-backend = "flit_core.buildapi"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Other changes include:
.INDENT 0.0
.IP \(bu 2
Support for storing your code under a \fBsrc/\fP folder (
.nf
:ghpull:\(ga260\(ga
.fi
).
You don\(aqt need to change any configuration if you do this.
.IP \(bu 2
Options to control what files are included in an sdist \- see
pyproject_toml_sdist for the details.
.IP \(bu 2
Requirements can specify a URL \(aqdirect reference\(aq, as an alternative to a
version number, with the syntax defined in \fI\%PEP 440\fP <\fBhttps://www.python.org/dev/peps/pep-0440\fP>:
\fBrequests @ https://example.com/requests\-2.22.0.tar.gz\fP\&.
.IP \(bu 2
Fix the shebang of scripts installed with the \fB\-\-python\fP option and the
\fB\-\-symlink\fP flag (
.nf
:ghpull:\(ga286\(ga
.fi
).
.IP \(bu 2
Installing with \fB\-\-deps develop\fP now installs normal dependencies
as well as development dependencies.
.IP \(bu 2
Author email is no longer required in the metadata table (
.nf
:ghpull:\(ga289\(ga
.fi
).
.IP \(bu 2
More error messages are now shown without a traceback (
.nf
:ghpull:\(ga254\(ga
.fi
)
.UNINDENT
.SS Version 1.3
.INDENT 0.0
.IP \(bu 2
Fix for building sdists from a subdirectory in a Mercurial repository
(
.nf
:ghpull:\(ga233\(ga
.fi
).
.IP \(bu 2
Fix for getting the docstring and version from modules defining their encoding
(
.nf
:ghpull:\(ga239\(ga
.fi
).
.IP \(bu 2
Fix for installing packages with \fBflit installfrom\fP (
.nf
:ghpull:\(ga221\(ga
.fi
).
.IP \(bu 2
Packages with requirements no longer get a spurious \fBProvides\-Extra: .none\fP
metadata entry (
.nf
:ghissue:\(ga228\(ga
.fi
).
.IP \(bu 2
Better check of whether \fBpython\-requires\fP includes any Python 2 version
(
.nf
:ghpull:\(ga232\(ga
.fi
).
.IP \(bu 2
Better check of home page URLs in \fBflit init\fP (
.nf
:ghpull:\(ga230\(ga
.fi
).
.IP \(bu 2
Better error message when the description file is not found (
.nf
:ghpull:\(ga234\(ga
.fi
).
.IP \(bu 2
Updated a help message to refer to \fBpyproject.toml\fP (
.nf
:ghpull:\(ga240\(ga
.fi
).
.IP \(bu 2
Improve tests of \fBflit init\fP (
.nf
:ghpull:\(ga229\(ga
.fi
).
.UNINDENT
.SS Version 1.2.1
.INDENT 0.0
.IP \(bu 2
Fix for installing packages with \fBflit install\fP\&.
.IP \(bu 2
Make \fBrequests_download\fP an extra dependency, to avoid a circular build
dependency. To use \fBflit installfrom\fP, you can install with
\fBpip install flit[installfrom]\fP\&. Note that the \fBinstallfrom\fP subcommand
is deprecated, as it will soon be possible to use pip to install Flit projects
directly from a VCS URL.
.UNINDENT
.SS Version 1.2
.INDENT 0.0
.IP \(bu 2
Fixes for packages specifying \fBrequires\-extra\fP: sdists should now work, and
environment markers can be used together with \fBrequires\-extra\fP\&.
.IP \(bu 2
Fix running \fBflit installfrom\fP without a config file present in the
working directory.
.IP \(bu 2
The error message for a missing or empty docstring tells you what file
the docstring should be in.
.IP \(bu 2
Improvements to documentation on version selectors for requirements.
.UNINDENT
.SS Version 1.1
.INDENT 0.0
.IP \(bu 2
Packages can now have \(aqextras\(aq, specified as \fBrequires\-extra\fP in the
pyproject.toml file\&. These are additional dependencies
for optional features.
.IP \(bu 2
The \fBhome\-page\fP metadata field is no longer required.
.IP \(bu 2
Additional project URLs are now validated.
.IP \(bu 2
\fBflit \-V\fP is now equivalent to \fBflit \-\-version\fP\&.
.IP \(bu 2
Various improvements to documentation.
.UNINDENT
.SS Version 1.0
.INDENT 0.0
.IP \(bu 2
The description file may now be written in reStructuredText, Markdown or
plain text. The file extension should indicate which of these formats it is
(\fB\&.rst\fP, \fB\&.md\fP or \fB\&.txt\fP). Previously, only reStructuredText was
officially supported.
.IP \(bu 2
Multiple links (e.g. documentation, bug tracker) can now be specified in a
new [tool.flit.metadata.urls] section of
\fBpyproject.toml\fP\&.
.IP \(bu 2
Dependencies are now correctly installed to the target Python when you use
the \fB\-\-symlink\fP or \fB\-\-pth\-file\fP options.
.IP \(bu 2
Dependencies are only installed to the Python where Flit is running if
it fails to get the docstring and version number without them.
.IP \(bu 2
The commands deprecated in 0.13—\fBflit wheel\fP, \fBflit sdist\fP and
\fBflit register\fP—have been removed.
.UNINDENT
.sp
Although version 1.0 sounds like a milestone, there\(aqs nothing that makes this
release especially significant. It doesn\(aqt 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.
.SS Version 0.13
.INDENT 0.0
.IP \(bu 2
Better validation of several metadata fields (\fBdist\-name\fP, \fBrequires\fP,
\fBrequires\-python\fP, \fBhome\-page\fP), and of the version number.
.IP \(bu 2
New \fBFLIT_ALLOW_INVALID\fP environment variable to ignore validation
failures in case they go wrong.
.IP \(bu 2
The list of valid classifiers is now fetched from Warehouse (\fI\%https://pypi.org\fP),
rather than the older \fI\%https://pypi.python.org\fP site.
.IP \(bu 2
Deprecated \fBflit wheel\fP and \fBflit sdist\fP subcommands: use
build_cmd\&.
.IP \(bu 2
Deprecated \fBflit register\fP: you can no longer register a package separately
from uploading it.
.UNINDENT
.SS Version 0.12.3
.INDENT 0.0
.IP \(bu 2
Fix building and installing packages with a \fB\-\fP in the distribution name.
.IP \(bu 2
Fix numbering in README.
.UNINDENT
.SS Version 0.12.2
.INDENT 0.0
.IP \(bu 2
New tool to convert \fBflit.ini\fP to \fBpyproject.toml\fP:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
python3 \-m flit.tomlify
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Use the PAX tar format for sdists, as specified by PEP 517.
.UNINDENT
.SS Version 0.12.1
.INDENT 0.0
.IP \(bu 2
Restore dependency on \fBzipfile36\fP backport package.
.IP \(bu 2
Add some missing options to documentation of \fBflit install\fP subcommand.
.IP \(bu 2
Rearrange environment variables in the docs.
.UNINDENT
.SS Version 0.12
.INDENT 0.0
.IP \(bu 2
Switch the config to \fBpyproject.toml\fP by default instead of \fBflit.ini\fP,
and implement the PEP 517 API.
.IP \(bu 2
A new option \fB\-\-pth\-file\fP allows for development installation on Windows
(where \fB\-\-symlink\fP usually won\(aqt work).
.IP \(bu 2
Normalise file permissions in the zip file, making builds more reproducible
across different systems.
.IP \(bu 2
Sdists (.tar.gz packages) can now also be reproducibly built by setting
\fBSOURCE_DATE_EPOCH\fP\&.
.IP \(bu 2
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.
.IP \(bu 2
\fBflit build\fP will build the wheel from the sdist, helping to ensure that
files aren\(aqt left out of the sdist.
.IP \(bu 2
All list fields in the INI file now ignore blank lines (\fBrequires\fP,
\fBdev\-requires\fP, \fBclassifiers\fP).
.IP \(bu 2
Fix the path separator in the \fBRECORD\fP file of a wheel built on Windows.
.IP \(bu 2
Some minor fixes to building reproducible wheels.
.IP \(bu 2
If building a wheel fails, the temporary file created will be cleaned up.
.IP \(bu 2
Various improvements to docs and README.
.UNINDENT
.SS Version 0.11.4
.INDENT 0.0
.IP \(bu 2
Explicitly open various files as UTF\-8, rather than relying on locale
encoding.
.IP \(bu 2
Link to docs from README.
.IP \(bu 2
Better test coverage, and a few minor fixes for problems revealed by tests.
.UNINDENT
.SS Version 0.11.3
.INDENT 0.0
.IP \(bu 2
Fixed a bug causing failed uploads when the password is entered in the
terminal.
.UNINDENT
.SS Version 0.11.2
.INDENT 0.0
.IP \(bu 2
A couple of behaviour changes when uploading to warehouse.
.UNINDENT
.SS Version 0.11.1
.INDENT 0.0
.IP \(bu 2
Fixed a bug when you use flit to build an sdist from a subdirectory inside a
VCS checkout. The VCS is now correctly detected.
.IP \(bu 2
Fix the rst checker for newer versions of docutils, by upgrading the bundled
copy of readme_renderer.
.UNINDENT
.SS Version 0.11
.INDENT 0.0
.IP \(bu 2
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:
.INDENT 2.0
.IP \(bu 2
\fBflit build\fP builds both a wheel and an sdist.
.IP \(bu 2
\fBflit publish\fP builds and uploads a wheel and an sdist.
.UNINDENT
.IP \(bu 2
Smarter ways of getting the information needed for upload:
.INDENT 2.0
.IP \(bu 2
If you have the \fI\%keyring\fP <\fBhttps://github.com/jaraco/keyring\fP> package
installed, flit can use it to store your password, rather than keeping it
in plain text in \fB~/.pypirc\fP\&.
.IP \(bu 2
If \fB~/.pypirc\fP does not already exist, and you are prompted for your
username, flit will write it into that file.
.IP \(bu 2
You can provide the information as environment variables:
\fBFLIT_USERNAME\fP, \fBFLIT_PASSWORD\fP and \fBFLIT_INDEX_URL\fP\&.
Use this to upload packages from a CI service, for instance.
.UNINDENT
.IP \(bu 2
Include \(aqLICENSE\(aq or \(aqCOPYING\(aq files in wheels.
.IP \(bu 2
Fix for \fBflit install \-\-symlink\fP inside a virtualenv.
.UNINDENT
.SS Version 0.10
.INDENT 0.0
.IP \(bu 2
Downstream packagers can use the \fBFLIT_NO_NETWORK\fP environment
variable to stop flit downloading data from the network.
.UNINDENT
.SS Version 0.9
.INDENT 0.0
.IP \(bu 2
\fBflit install\fP and \fBflit installfrom\fP now take an optional \fB\-\-python\fP argument,
with the path to the Python executable you want to install it for.
Using this, you can install modules to Python 2.
.IP \(bu 2
Installing a module normally (without \fB\-\-symlink\fP) builds a wheel and uses
pip to install it, which should work better in some corner cases.
.UNINDENT
.SS Version 0.8
.INDENT 0.0
.IP \(bu 2
A new \fBflit installfrom\fP subcommand to install a project from a source
archive, such as from Github.
.IP \(bu 2
Reproducible builds \- you can produce byte\-for\-byte
identical wheels.
.IP \(bu 2
A warning for non\-canonical version numbers according to \fI\%PEP 440\fP <\fBhttps://www.python.org/dev/peps/pep-0440/\fP>\&.
.IP \(bu 2
Fix for installing projects on Windows.
.IP \(bu 2
Better error message when module docstring is only whitespace.
.UNINDENT
.SS Version 0.7
.INDENT 0.0
.IP \(bu 2
A new \fBdev\-requires\fP field in the config file for development requirements,
used when doing \fBflit install\fP\&.
.IP \(bu 2
Added a \fB\-\-deps\fP option for \fBflit install\fP to control which dependencies
are installed.
.IP \(bu 2
Flit can now be invoked with \fBpython \-m flit\fP\&.
.UNINDENT
.SS Version 0.6
.INDENT 0.0
.IP \(bu 2
\fBflit install\fP now ensures requirements specified in \fBflit.ini\fP are
installed, using pip.
.IP \(bu 2
If you specify a description file, flit now warns you if it\(aqs not valid
reStructuredText (since invalid reStructuredText is treated as plain text on
PyPI).
.IP \(bu 2
Improved the error message for mis\-spelled keys in \fBflit.ini\fP\&.
.UNINDENT
.SS Version 0.5
.INDENT 0.0
.IP \(bu 2
A new \fBflit init\fP command to quickly define the essential basic metadata
for a package.
.IP \(bu 2
Support for entry points.
.IP \(bu 2
A new \fBflit register\fP command to register a package without uploading it,
for when you want to claim a name before you\(aqre ready to release.
.IP \(bu 2
Added a \fB\-\-repository\fP option for specifying an alternative PyPI instance.
.IP \(bu 2
Added a \fB\-\-debug\fP flag to show debug\-level log messages.
.IP \(bu 2
Better error messages when the module docstring or \fB__version__\fP is missing.
.UNINDENT
.SS Version 0.4
.INDENT 0.0
.IP \(bu 2
Users can now specify \fBdist\-name\fP in the config file if they need to use
different names on PyPI and for imports.
.IP \(bu 2
Classifiers are now checked against a locally cached list of valid
classifiers.
.IP \(bu 2
Packages can be locally installed into environments for development.
.IP \(bu 2
Local installation now creates a PEP 376 \fB\&.dist\-info\fP folder instead of
\fB\&.egg\-info\fP\&.
.UNINDENT
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
Thomas Kluyver
.SH COPYRIGHT
2022, Thomas Kluyver
.\" Generated by docutils manpage writer.
.