diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/Makefile | 177 | ||||
| -rw-r--r-- | doc/_static/flit_logo_nobg.svg | 149 | ||||
| -rw-r--r-- | doc/_static/flit_logo_nobg_cropped.png | bin | 0 -> 5890 bytes | |||
| -rw-r--r-- | doc/_static/flit_logo_nobg_cropped.svg | 158 | ||||
| -rw-r--r-- | doc/bootstrap.rst | 41 | ||||
| -rw-r--r-- | doc/cmdline.rst | 262 | ||||
| -rw-r--r-- | doc/conf.py | 264 | ||||
| -rw-r--r-- | doc/development.rst | 26 | ||||
| -rw-r--r-- | doc/flit_ini.rst | 113 | ||||
| -rw-r--r-- | doc/history.rst | 497 | ||||
| -rw-r--r-- | doc/index.rst | 34 | ||||
| -rw-r--r-- | doc/make.bat | 242 | ||||
| -rw-r--r-- | doc/pyproject_toml.rst | 480 | ||||
| -rw-r--r-- | doc/rationale.rst | 58 | ||||
| -rw-r--r-- | doc/reproducible.rst | 34 | ||||
| -rw-r--r-- | doc/requirements.txt | 3 | ||||
| -rw-r--r-- | doc/upload.rst | 77 |
17 files changed, 2615 insertions, 0 deletions
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 <target>' where <target> 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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="293.71423" + height="293.71423" + id="svg3116" + version="1.1" + inkscape:version="0.48.5 r10040" + sodipodi:docname="New document 2"> + <defs + id="defs3118"> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4452" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(2.0646126,0,0,2.0646126,2131.1883,-505.68517)" + x1="294.93112" + y1="187.01703" + x2="536.55017" + y2="453.6973" /> + <linearGradient + inkscape:collect="always" + id="linearGradient4432"> + <stop + style="stop-color:#00c48a;stop-opacity:1" + offset="0" + id="stop4434" /> + <stop + style="stop-color:#00cbff;stop-opacity:1" + offset="1" + id="stop4436" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4460" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4454" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4456" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4458" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.98994949" + inkscape:cx="421.10472" + inkscape:cy="117.57302" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + inkscape:window-width="1680" + inkscape:window-height="987" + inkscape:window-x="1680" + inkscape:window-y="27" + inkscape:window-maximized="1" /> + <metadata + id="metadata3121"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-204.57382,-259.79316)"> + <g + transform="matrix(0.24278029,0,0,0.24278029,-425.3047,353.61591)" + id="g4440"> + <path + id="path4442" + style="fill:url(#linearGradient4452);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="m 3027.3295,254.07953 c -13.7048,13.09172 -26.0357,28.06465 -37.0176,44.61328 l 0,41.02539 c 0,5.00744 1.7866,9.29826 5.3633,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 5.3651,0 9.8353,-1.7885 13.4121,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-85.63867 z m 40.2012,-35.61328 -40.2012,0 0,35.61328 c 2.8934,-2.76398 5.8436,-5.45128 8.8594,-8.04492 11.4454,-9.57254 21.8635,-18.67845 31.3418,-27.56836 z m 34.6465,-37.01953 c -9.7805,12.36045 -21.2701,24.47349 -34.6465,37.01953 l 46.7148,0 c 5.0075,0 9.2983,-1.78849 12.875,-5.36524 3.5768,-3.57674 5.3653,-7.86951 5.3653,-12.87695 0,-5.36511 -1.7885,-9.83537 -5.3653,-13.41211 -3.5767,-3.57674 -7.8675,-5.36523 -12.875,-5.36523 l -12.0683,0 z m 33.4824,-60.625 -108.3301,0 0,60.625 74.8477,0 c 14.8892,-18.81683 25.825,-38.22167 33.4824,-60.625 z m 9.5449,-37.019527 c -1.2585,5.3045 -2.516,10.94337 -3.7636,17.044917 -1.6666,6.94336 -3.5949,13.57773 -5.7813,19.97461 l 23.6523,0 c 5.0075,0 9.3003,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.007437 -1.7885,-9.298257 -5.3652,-12.874997 -3.5767,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -14.1074,0 z m -476.3222,-177.33008 c -2.0115,-10e-4 -4.0205,0.0285 -6.0352,0.0957 -32.2353,1.07179 -39.6278,16.38542 -12.3691,36.69141 27.2586,20.30597 67.4768,42.69338 95.8925,62.71679 28.4157,20.02339 35.7846,52.54784 62.5118,70.95899 26.7272,18.41115 54.3969,37.466677 74.8691,57.441407 20.4723,19.97478 42.8139,29.80954 62.9473,12.42382 -41.9066,63.48263 12.2332,134.84987 -173.1446,298.5918 29.2843,16.0722 57.5499,-20.52973 74.8907,-31.10547 2.5476,26.72831 -25.0012,91.1355 -29.2129,135.5625 21.025,-46.6543 56.9285,-120.22794 63.457,-115.36328 9.8881,7.3681 14.1396,135.40743 24.3965,116.33203 21.0116,-25.8867 22.3263,-107.36363 34.0937,-138.89062 11.2667,-42.29933 27.605,-80.7941 49.1328,-113.23438 l 0,-196.65039 c 0,-5.007437 1.7866,-9.298257 5.3633,-12.874997 3.5768,-3.57674 7.8695,-5.36523 12.877,-5.36523 l 136.6523,0 c 15.517,-65.40122 31.2666,-72.74791 32.5215,-83.04883003 13.2678,-9.65059997 122.3748,-33.57495997 180.1094,-40.48437997 -50.3218,-5.57548 -143.4532,11.69044 -195.586,7.36328 -73.7651,-34.78206 -111.4896,10.40375 -121.4531,64.52149 -83.501,33.35098 -204.8488,-83.78957 -259.7637,-101.41602 -51.4826,-16.52477 -81.9782,-24.2477 -112.1503,-24.26562 z m 83.1191,-45.779303 c -0.8667,-0.008 -1.7091,4.6e-4 -2.5293,0.0254 -22.9645,0.69796 -27.5787,14.12698 -6.4688,35.07813 7.5478,7.490993 16.3801,15.378493 25.6504,23.388673 3.4327,1.07931 6.7052,2.08334 10.3399,3.25 54.6631,17.54562 175.142,133.67703 258.6035,101.84765 -64.3681,-33.00238 -126.9043,-104.68293 -163.5801,-122.48828 -48.6408,-23.613873 -77.7408,-35.557113 -107.6094,-39.826173 -1.9912,-0.28458 -3.988,-0.53646 -5.9921,-0.7539 -3.0061,-0.32634 -5.8141,-0.49799 -8.4141,-0.52149 z" + inkscape:connector-curvature="0" /> + <g + id="g4444" + style="fill:url(#linearGradient4460);fill-opacity:1" + transform="translate(-52.527932,-383.85797)"> + <path + id="path4446" + d="m 3295.8047,467.66016 c -5.0075,0 -9.3002,1.78849 -12.877,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 l 150.7598,0 c 5.0074,0 9.2982,-1.7885 12.875,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 0,-5.36511 -1.7885,-9.83732 -5.3652,-13.41406 -3.5768,-3.57674 -7.8676,-5.36328 -12.875,-5.36328 l -131.9825,0 0,-218.89844 c 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.047,-5.36523 -13.4121,-5.36523 z" + style="fill:url(#linearGradient4454);fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + id="path4448" + d="m 3532.623,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8676,5.36524 12.875,5.36524 5.3652,0 9.8374,-1.7885 13.4141,-5.36524 3.5768,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-237.67578 c 0,-5.00744 -1.7884,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.0489,-5.36523 -13.4141,-5.36523 z" + style="fill:url(#linearGradient4456);fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + id="path4450" + d="m 3617.123,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 0,5.00744 1.7885,9.47965 5.3652,13.41406 3.5768,3.57675 7.8676,5.36524 12.875,5.36524 l 56.8711,0 0,218.89648 c 0,5.00744 1.7885,9.29826 5.3653,12.875 3.5767,3.57674 7.8695,5.36524 12.8769,5.36524 5.3651,0 9.8354,-1.7885 13.4121,-5.36524 3.5768,-3.57674 5.3653,-7.86756 5.3653,-12.875 l 0,-218.89648 56.8691,0 c 5.0075,0 9.3002,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5768,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -150.7598,0 z" + style="fill:url(#linearGradient4458);fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + </g> + </g> + </g> +</svg> diff --git a/doc/_static/flit_logo_nobg_cropped.png b/doc/_static/flit_logo_nobg_cropped.png Binary files differnew file mode 100644 index 0000000..5385556 --- /dev/null +++ b/doc/_static/flit_logo_nobg_cropped.png 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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="293.54721" + height="194.0495" + id="svg3116" + version="1.1" + inkscape:version="0.48.5 r10040" + sodipodi:docname="flit_logo_nobg.svg"> + <defs + id="defs3118"> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4452" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(2.0646126,0,0,2.0646126,2131.1883,-505.68517)" + x1="294.93112" + y1="187.01703" + x2="536.55017" + y2="453.6973" /> + <linearGradient + inkscape:collect="always" + id="linearGradient4432"> + <stop + style="stop-color:#00c48a;stop-opacity:1" + offset="0" + id="stop4434" /> + <stop + style="stop-color:#00cbff;stop-opacity:1" + offset="1" + id="stop4436" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4460" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4454" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4456" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient4458" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient4432" + id="linearGradient3991" + gradientUnits="userSpaceOnUse" + x1="3277.5625" + y1="604.73828" + x2="3786.125" + y2="604.73828" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.4" + inkscape:cx="221.08413" + inkscape:cy="35.027636" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + inkscape:window-width="1680" + inkscape:window-height="987" + inkscape:window-x="1680" + inkscape:window-y="27" + inkscape:window-maximized="1" /> + <metadata + id="metadata3121"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-204.65524,-306.77908)"> + <g + transform="matrix(0.24278029,0,0,0.24278029,-425.3047,353.61591)" + id="g4440"> + <path + id="path4442" + style="fill:url(#linearGradient4452);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="m 3027.3295,254.07953 c -13.7048,13.09172 -26.0357,28.06465 -37.0176,44.61328 l 0,41.02539 c 0,5.00744 1.7866,9.29826 5.3633,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 5.3651,0 9.8353,-1.7885 13.4121,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-85.63867 z m 40.2012,-35.61328 -40.2012,0 0,35.61328 c 2.8934,-2.76398 5.8436,-5.45128 8.8594,-8.04492 11.4454,-9.57254 21.8635,-18.67845 31.3418,-27.56836 z m 34.6465,-37.01953 c -9.7805,12.36045 -21.2701,24.47349 -34.6465,37.01953 l 46.7148,0 c 5.0075,0 9.2983,-1.78849 12.875,-5.36524 3.5768,-3.57674 5.3653,-7.86951 5.3653,-12.87695 0,-5.36511 -1.7885,-9.83537 -5.3653,-13.41211 -3.5767,-3.57674 -7.8675,-5.36523 -12.875,-5.36523 l -12.0683,0 z m 33.4824,-60.625 -108.3301,0 0,60.625 74.8477,0 c 14.8892,-18.81683 25.825,-38.22167 33.4824,-60.625 z m 9.5449,-37.019527 c -1.2585,5.3045 -2.516,10.94337 -3.7636,17.044917 -1.6666,6.94336 -3.5949,13.57773 -5.7813,19.97461 l 23.6523,0 c 5.0075,0 9.3003,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.007437 -1.7885,-9.298257 -5.3652,-12.874997 -3.5767,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -14.1074,0 z m -476.3222,-177.33008 c -2.0115,-10e-4 -4.0205,0.0285 -6.0352,0.0957 -32.2353,1.07179 -39.6278,16.38542 -12.3691,36.69141 27.2586,20.30597 67.4768,42.69338 95.8925,62.71679 28.4157,20.02339 35.7846,52.54784 62.5118,70.95899 26.7272,18.41115 54.3969,37.466677 74.8691,57.441407 20.4723,19.97478 42.8139,29.80954 62.9473,12.42382 -41.9066,63.48263 12.2332,134.84987 -173.1446,298.5918 29.2843,16.0722 57.5499,-20.52973 74.8907,-31.10547 2.5476,26.72831 -25.0012,91.1355 -29.2129,135.5625 21.025,-46.6543 56.9285,-120.22794 63.457,-115.36328 9.8881,7.3681 14.1396,135.40743 24.3965,116.33203 21.0116,-25.8867 22.3263,-107.36363 34.0937,-138.89062 11.2667,-42.29933 27.605,-80.7941 49.1328,-113.23438 l 0,-196.65039 c 0,-5.007437 1.7866,-9.298257 5.3633,-12.874997 3.5768,-3.57674 7.8695,-5.36523 12.877,-5.36523 l 136.6523,0 c 15.517,-65.40122 31.2666,-72.74791 32.5215,-83.04883003 13.2678,-9.65059997 122.3748,-33.57495997 180.1094,-40.48437997 -50.3218,-5.57548 -143.4532,11.69044 -195.586,7.36328 -73.7651,-34.78206 -111.4896,10.40375 -121.4531,64.52149 -83.501,33.35098 -204.8488,-83.78957 -259.7637,-101.41602 -51.4826,-16.52477 -81.9782,-24.2477 -112.1503,-24.26562 z m 83.1191,-45.779303 c -0.8667,-0.008 -1.7091,4.6e-4 -2.5293,0.0254 -22.9645,0.69796 -27.5787,14.12698 -6.4688,35.07813 7.5478,7.490993 16.3801,15.378493 25.6504,23.388673 3.4327,1.07931 6.7052,2.08334 10.3399,3.25 54.6631,17.54562 175.142,133.67703 258.6035,101.84765 -64.3681,-33.00238 -126.9043,-104.68293 -163.5801,-122.48828 -48.6408,-23.613873 -77.7408,-35.557113 -107.6094,-39.826173 -1.9912,-0.28458 -3.988,-0.53646 -5.9921,-0.7539 -3.0061,-0.32634 -5.8141,-0.49799 -8.4141,-0.52149 z" + inkscape:connector-curvature="0" /> + <g + id="g4444" + style="fill:url(#linearGradient3991);fill-opacity:1" + transform="translate(-52.527932,-383.85797)"> + <path + id="path4446" + d="m 3295.8047,467.66016 c -5.0075,0 -9.3002,1.78849 -12.877,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 l 150.7598,0 c 5.0074,0 9.2982,-1.7885 12.875,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 0,-5.36511 -1.7885,-9.83732 -5.3652,-13.41406 -3.5768,-3.57674 -7.8676,-5.36328 -12.875,-5.36328 l -131.9825,0 0,-218.89844 c 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.047,-5.36523 -13.4121,-5.36523 z" + style="fill:url(#linearGradient4454);fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + id="path4448" + d="m 3532.623,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8676,5.36524 12.875,5.36524 5.3652,0 9.8374,-1.7885 13.4141,-5.36524 3.5768,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-237.67578 c 0,-5.00744 -1.7884,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.0489,-5.36523 -13.4141,-5.36523 z" + style="fill:url(#linearGradient4456);fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + id="path4450" + d="m 3617.123,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 0,5.00744 1.7885,9.47965 5.3652,13.41406 3.5768,3.57675 7.8676,5.36524 12.875,5.36524 l 56.8711,0 0,218.89648 c 0,5.00744 1.7885,9.29826 5.3653,12.875 3.5767,3.57674 7.8695,5.36524 12.8769,5.36524 5.3651,0 9.8354,-1.7885 13.4121,-5.36524 3.5768,-3.57674 5.3653,-7.86756 5.3653,-12.875 l 0,-218.89648 56.8691,0 c 5.0075,0 9.3002,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5768,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -150.7598,0 z" + style="fill:url(#linearGradient4458);fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + </g> + </g> + </g> +</svg> 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 +<https://pypi.org/project/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 <https://pypi.org/project/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 <path>, --ini-file <path> + + 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 <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 <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 <repository> + + Name of a repository to upload packages to. Should match a section in + ``~/.pypirc``. The default is ``pypi``. + +.. option:: --pypirc <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 <dependency option> + + 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 <extra[,extra,...]> + + 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 <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 :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 + <https://pip.pypa.io/en/stable/topics/configuration/#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 <upload_envvars>` + 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 <https://github.com/pypa/flit/issues>`__. + +.. 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 + <https://reproducible-builds.org/specs/source-date-epoch/>`__ + 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 +# "<project> v<release> 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 <link> 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 <https://tox.readthedocs.io/en/latest/>`_ 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 <pyproject_toml>` 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 + <https://www.python.org/dev/peps/pep-0345/#environment-markers>`_ + 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 + <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, 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 <https://pypi.python.org/pypi?%3Aaction=list_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 <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 <pyproject_toml_external_data>` 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 <bootstrap>` a Python environment, + e.g. for downstream packagers (:ghpull:`511`). ``flit_core.wheel`` is usable + with ``python -m`` to create wheels before the `build <https://pypi.org/project/build/>`_ + tool is available, and ``flit_core`` sdists also include a script to install + itself from a wheel before `installer <https://pypi.org/project/installer/>`_ + is available. +- Use newer importlib APIs, fixing some deprecation warnings (:ghpull:`499`). + +Version 3.6 +----------- + +- ``flit_core`` now bundles the `tomli <https://pypi.org/project/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 <bootstrap>`. + +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 <https://pypi.org/project/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 <pyproject_toml_project>`. 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 <cmdline>` 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 <pyproject_toml>`. 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 <pyproject_toml_urls>` 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 <https://github.com/jaraco/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 <reproducible>` - you can produce byte-for-byte + identical wheels. +- A warning for non-canonical version numbers according to `PEP 440 + <https://www.python.org/dev/peps/pep-0440/>`__. +- 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 + + <img src="_static/flit_logo_nobg_cropped.svg" width="200px" style="float: right"/> + +.. 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 ^<target^>` where ^<target^> 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 <flit_ini>` 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 <flit_ini>` 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 + <https://toml.io/en/v0.5.0>`_. +- 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 <pyproject_old_metadata>`), +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 + <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, 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 <https://pypi.python.org/pypi?%3Aaction=list_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 <https://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 <http://entrypoints.readthedocs.io/en/latest/>`_ +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 +<pyproject_project_scripts>`, 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 <pyproject_toml_project>`), 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 + <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, Markdown or + plain text, and the filename should have the appropriate extension + (``.rst``, ``.md`` or ``.txt``). +classifiers + A list of `Trove classifiers <https://pypi.python.org/pypi?%3Aaction=list_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 <https://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 <pyproject_project_scripts>`. + +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_project_entrypoints>`. + +.. _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 <reproducible>`, +a feature which some people care about. + +There have been many other efforts to improve the user experience of Python +packaging, such as `pbr <https://pypi.org/project/pbr/>`_, but before Flit, +these tended to build on setuptools and distutils. That was a pragmatic +decision, but it's hard to build something radically different on top of those +libraries. The existence of Flit spurred the development of new standards, +like :pep:`518` and :pep:`517`, which are now used by other packaging tools +such as `Poetry <https://python-poetry.org/>`_ and +`Enscons <https://pypi.org/project/enscons/>`_. + +Other options +------------- + +If your package needs a build step, you won't be able to use Flit. +`Setuptools <https://setuptools.readthedocs.io/en/latest/>`_ is the de-facto +standard, but newer tools such as Enscons_ also cover this case. + +Flit also doesn't help you manage dependencies: you have to add them to +``pyproject.toml`` by hand. Tools like Poetry_ and `Pipenv +<https://pypi.org/project/pipenv/>`_ have features which help add and update +dependencies on other packages. 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 <https://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 <https://pypi.org/>`_, +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 +<https://pypi.python.org/pypi/twine>`_. + +For instance, to upload a package to the `Test PyPI server <https://test.pypi.org/>`_ +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 <https://pypi.python.org/pypi/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 <https://www.diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/>`_. + 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. |
