diff options
Diffstat (limited to 'docs')
62 files changed, 16426 insertions, 16 deletions
diff --git a/docs/artwork.rst b/docs/artwork.rst new file mode 100644 index 00000000..907e62a6 --- /dev/null +++ b/docs/artwork.rst @@ -0,0 +1,119 @@ +======= +Artwork +======= + +.. figure:: images/logo-over-white.svg + :align: center + + Setuptools logo, designed in 2021 by `Anderson Bravalheri`_ + +Elements of Design +================== + +The main colours of the design are a dark pastel azure (``#336790``) and a pale +orange (``#E5B62F``), referred in this document simply as "blue" and "yellow" +respectively. The text uses the *Monoid* typeface, an open source webfont that +was developed by Andreas Larsen and contributors in 2015 and is distributed +under the MIT or SIL licenses (more information at +https://github.com/larsenwork/monoid) + + +Usage +===== + +The preferred way of using the setuptools logo is over a white (or light) +background. Alternatively, the following options can be considered, depending +on the circumstances: + +- *"negative"* design - for dark backgrounds (e.g. website displayed in "dark + mode"): the white colour (``#FFFFFF``) of the background and the "blue" + (``#336790``) colour of the design can be swapped. +- *"monochrome"* - when colours are not available (e.g. black and white printed + media): a completely black or white version of the logo can also be used. +- *"banner"* mode: the symbol and text can be used alongside depending on the + available space. + +The following image illustrate these alternatives: + +.. image:: images/logo-demo.svg + :align: center + +Please refer to the SVG files in the `setuptools repository`_ for the specific +shapes and proportions between the elements of the design. + + +Working with the Design +======================= + +The `setuptools repository`_ contains a series of vector representations of the +design under the ``docs/images`` directory. These representations can be +manipulated via any graphic editor that support SVG files, +however the free and open-source software Inkscape_ is recommended for maximum +compatibility. + +When selecting the right file to work with, file names including +``editable-inkscape`` indicate "more editable" elements (e.g. editable text), +while the others prioritise SVG paths for maximum reproducibility. + +Also notice that you might have to `install the correct fonts`_ to be able to +visualise or edit some of the designs. + + +Inspiration +=========== + +This design was inspired by :user:`cajhne`'s `original proposal`_ and the +ancient symbol of the ouroboros_. +It features a snake moving in a circular trajectory not only as a reference to +the Python programming language but also to the `wheel package format`_ as one +of the distribution formats supported by setuptools. +The shape of the snake also resembles a cog, which together with the hammer is +a nod to the two words that compose the name of the project. + + +License +======= + + +This logo, design variations or a modified version may be used by anyone to +refer to setuptools, but does not indicate endorsement by the project. + +Redistribution, usage and derivative works are permitted under the same license +used by the setuptools software (MIT): + +.. code-block:: text + + Copyright (c) Anderson Bravalheri + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to + deal in the Software without restriction, including without limitation the + rights to use, copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + IN THE SOFTWARE. + + THE USAGE OF THIS LOGO AND ARTWORK DOES NOT INDICATE ENDORSEMENT BY THE + SETUPTOOLS PROJECT. + +Whenever possible, please make the image a link to +https://github.com/pypa/setuptools or https://setuptools.pypa.io. + + +.. _Anderson Bravalheri: https://github.com/abravalheri +.. _Inkscape: https://inkscape.org +.. _setuptools repository: https://github.com/pypa/setuptools +.. _install the correct fonts: https://wiki.inkscape.org/wiki/Installing_fonts +.. _original proposal: https://github.com/pypa/setuptools/issues/2227#issuecomment-653628344 +.. _wheel package format: https://www.python.org/dev/peps/pep-0427/ +.. _ouroboros: https://en.wikipedia.org/wiki/Ouroboros diff --git a/docs/build_meta.rst b/docs/build_meta.rst new file mode 100644 index 00000000..37738b8f --- /dev/null +++ b/docs/build_meta.rst @@ -0,0 +1,182 @@ +======================================= +Build System Support +======================================= + +What is it? +------------- + +Python packaging has come `a long way <https://bernat.tech/posts/pep-517-518/>`_. + +The traditional ``setuptools`` way of packaging Python modules +uses a ``setup()`` function within the ``setup.py`` script. Commands such as +``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a +distribution bundle and ``python setup.py install`` installs the distribution. +This interface makes it difficult to choose other packaging tools without an +overhaul. Because ``setup.py`` scripts allow for arbitrary execution, it +is difficult to provide a reliable user experience across environments +and history. + +`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ came to +the rescue and specified a new standard for packaging and distributing Python +modules. Under PEP 517: + + A ``pyproject.toml`` file is used to specify which program to use + to generate the distribution. + + Two functions provided by the program, ``build_wheel(directory: str)`` + and ``build_sdist(directory: str)``, create the distribution bundle in the + specified ``directory``. + + The program may use its own configuration file or extend the ``.toml`` file. + + The actual installation is done with ``pip install *.whl`` or + ``pip install *.tar.gz``. If ``*.whl`` is available, ``pip`` will go ahead and copy + its files into the ``site-packages`` directory. If not, ``pip`` will look at + ``pyproject.toml`` and decide which program to use to 'build from source'. + (Note that if there is no ``pyproject.toml`` file or the ``build-backend`` + parameter is not defined, then the fall-back behaviour is to use ``setuptools``.) + +With this standard, switching between packaging tools is a lot easier. + +How to use it? +-------------- + +Start with a package that you want to distribute. You will need your source +files, a ``pyproject.toml`` file and a ``setup.cfg`` file:: + + ~/meowpkg/ + pyproject.toml + setup.cfg + meowpkg/ + __init__.py + module.py + +The ``pyproject.toml`` file specifies the build system (i.e. what is +being used to package your scripts and install from source). To use it with +``setuptools`` the content would be:: + + [build-system] + requires = ["setuptools"] + build-backend = "setuptools.build_meta" + +``build_meta`` implements ``setuptools``' build system support. +The ``setuptools`` package implements the ``build_sdist`` +command and the ``wheel`` package implements the ``build_wheel`` +command; the latter is a dependency of the former +exposed via :pep:`517` hooks. + +Use ``setuptools``' :ref:`declarative config <declarative config>` to +specify the package information in ``setup.cfg``:: + + [metadata] + name = meowpkg + version = 0.0.1 + description = a package that meows + + [options] + packages = find: + +.. _building: + +Now generate the distribution. To build the package, use +`PyPA build <https://pypa-build.readthedocs.io/en/latest/>`_:: + + $ pip install -q build + $ python -m build + +And now it's done! The ``.whl`` file and ``.tar.gz`` can then be distributed +and installed:: + + dist/ + meowpkg-0.0.1.whl + meowpkg-0.0.1.tar.gz + + $ pip install dist/meowpkg-0.0.1.whl + +or:: + + $ pip install dist/meowpkg-0.0.1.tar.gz + + +.. _backend-wrapper: + +Dynamic build dependencies and other ``build_meta`` tweaks +---------------------------------------------------------- + +With the changes introduced by :pep:`517` and :pep:`518`, the +``setup_requires`` configuration field was deprecated in ``setup.cfg`` and +``setup.py``, in favour of directly listing build dependencies in the +``requires`` field of the ``build-system`` table of ``pyproject.toml``. +This approach has a series of advantages and gives package managers and +installers the ability to inspect the build requirements in advance and +perform a series of optimisations. + +However, some package authors might still need to dynamically inspect the final +user's machine before deciding these requirements. One way of doing that, as +specified by :pep:`517`, is to "tweak" ``setuptools.build_meta`` by using an +:pep:`in-tree backend <517#in-tree-build-backends>`. + +.. tip:: Before implementing an *in-tree* backend, have a look at + :pep:`PEP 508 <508#environment-markers>`. Most of the time, dependencies + with **environment markers** are enough to differentiate operating systems + and platforms. + +If you put the following configuration in your ``pyproject.toml``: + +.. code-block:: toml + + [build-system] + requires = ["setuptools"] + build-backend = "backend" + backend-path = ["_custom_build"] + + +then you can implement a thin wrapper around ``build_meta`` in +the ``_custom_build/backend.py`` file, as shown in the following example: + +.. code-block:: python + + from setuptools import build_meta as _orig + + prepare_metadata_for_build_wheel = _orig.prepare_metadata_for_build_wheel + build_wheel = _orig.build_wheel + build_sdist = _orig.build_sdist + + + def get_requires_for_build_wheel(self, config_settings=None): + return _orig.get_requires_for_build_wheel(config_settings) + [...] + + + def get_requires_for_build_sdist(self, config_settings=None): + return _orig.get_requires_for_build_sdist(config_settings) + [...] + + +Note that you can override any of the functions specified in :pep:`PEP 517 +<517#build-backend-interface>`, not only the ones responsible for gathering +requirements. + +.. important:: Make sure your backend script is included in the :doc:`source + distribution </userguide/distribution>`, otherwise the build will fail. + This can be done by using a SCM_/VCS_ plugin (like :pypi:`setuptools-scm` + and :pypi:`setuptools-svn`), or by correctly setting up :ref:`MANIFEST.in + <manifest>`. + + The generated ``.tar.gz`` and ``.whl`` files are compressed archives that + can be inspected as follows: + On POSIX systems, this can be done with ``tar -tf dist/*.tar.gz`` + and ``unzip -l dist/*.whl``. + On Windows systems, you can rename the ``.whl`` to ``.zip`` to be able to + inspect it from File Explorer. You can also use the above ``tar`` command in a + command prompt to inspect the ``.tar.gz`` file. Alternatively, there are GUI programs + like `7-zip`_ that handle ``.tar.gz`` and ``.whl`` files. + + In general, the backend script should be present in the ``.tar.gz`` (so the + project can be built from the source) but not in the ``.whl`` (otherwise the + backend script would end up being distributed alongside your package). + See ":doc:`/userguide/package_discovery`" for more details about package + files. + + +.. _SCM: https://en.wikipedia.org/wiki/Software_configuration_management +.. _VCS: https://en.wikipedia.org/wiki/Version_control +.. _7-zip: https://www.7-zip.org diff --git a/docs/conf.py b/docs/conf.py index c2043393..a52569c9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,10 @@ html_theme = "furo" extensions += ['rst.linker'] link_files = { '../CHANGES.rst': dict( - using=dict(GH='https://github.com'), + using=dict( + BB='https://bitbucket.org', + GH='https://github.com', + ), replace=[ dict( pattern=r'(Issue #|\B#)(?P<issue>\d+)', @@ -24,8 +27,64 @@ link_files = { pattern=r'PEP[- ](?P<pep_number>\d+)', url='https://peps.python.org/pep-{pep_number:0>4}/', ), + dict( + pattern=r'(?<!\w)PR #(?P<pull>\d+)', + url='{package_url}/pull/{pull}', + ), + dict( + pattern=r'BB Pull Request ?#(?P<bb_pull_request>\d+)', + url='{BB}/pypa/setuptools/pull-request/{bb_pull_request}', + ), + dict( + pattern=r'Distribute #(?P<distribute>\d+)', + url='{BB}/tarek/distribute/issue/{distribute}', + ), + dict( + pattern=r'Buildout #(?P<buildout>\d+)', + url='{GH}/buildout/buildout/issues/{buildout}', + ), + dict( + pattern=r'Old Setuptools #(?P<old_setuptools>\d+)', + url='http://bugs.python.org/setuptools/issue{old_setuptools}', + ), + dict( + pattern=r'Jython #(?P<jython>\d+)', + url='http://bugs.jython.org/issue{jython}', + ), + dict( + pattern=r'(Python #|bpo-)(?P<python>\d+)', + url='http://bugs.python.org/issue{python}', + ), + dict( + pattern=r'Interop #(?P<interop>\d+)', + url='{GH}/pypa/interoperability-peps/issues/{interop}', + ), + dict( + pattern=r'Pip #(?P<pip>\d+)', + url='{GH}/pypa/pip/issues/{pip}', + ), + dict( + pattern=r'Packaging #(?P<packaging>\d+)', + url='{GH}/pypa/packaging/issues/{packaging}', + ), + dict( + pattern=r'[Pp]ackaging (?P<packaging_ver>\d+(\.\d+)+)', + url='{GH}/pypa/packaging/blob/{packaging_ver}/CHANGELOG.rst', + ), + dict( + pattern=r'setuptools_svn #(?P<setuptools_svn>\d+)', + url='{GH}/jaraco/setuptools_svn/issues/{setuptools_svn}', + ), + dict( + pattern=r'pypa/(?P<issue_repo>[\-\.\w]+)#(?P<issue_number>\d+)', + url='{GH}/pypa/{issue_repo}/issues/{issue_number}', + ), + dict( + pattern=r'pypa/(?P<commit_repo>[\-\.\w]+)@(?P<commit_number>[\da-f]+)', + url='{GH}/pypa/{commit_repo}/commit/{commit_number}', + ), ], - ) + ), } # Be strict about any broken references @@ -40,3 +99,149 @@ intersphinx_mapping = { # Preserve authored syntax for defaults autodoc_preserve_defaults = True + +intersphinx_mapping.update({ + 'pip': ('https://pip.pypa.io/en/latest', None), + 'build': ('https://pypa-build.readthedocs.io/en/latest', None), + 'PyPUG': ('https://packaging.python.org/en/latest/', None), + 'packaging': ('https://packaging.pypa.io/en/latest/', None), + 'twine': ('https://twine.readthedocs.io/en/stable/', None), + 'importlib-resources': ( + 'https://importlib-resources.readthedocs.io/en/latest', None + ), +}) + +# Support tooltips on references +extensions += ['hoverxref.extension'] +hoverxref_auto_ref = True +hoverxref_intersphinx = [ + 'python', + 'pip', + 'build', + 'PyPUG', + 'packaging', + 'twine', + 'importlib-resources', +] + +# Add support for linking usernames +github_url = 'https://github.com' +github_repo_org = 'pypa' +github_repo_name = 'setuptools' +github_repo_slug = f'{github_repo_org}/{github_repo_name}' +github_repo_url = f'{github_url}/{github_repo_slug}' +github_sponsors_url = f'{github_url}/sponsors' +extlinks = { + 'user': (f'{github_sponsors_url}/%s', '@%s'), # noqa: WPS323 + 'pypi': ('https://pypi.org/project/%s', '%s'), # noqa: WPS323 + 'wiki': ('https://wikipedia.org/wiki/%s', '%s'), # noqa: WPS323 +} +extensions += ['sphinx.ext.extlinks'] + +# Ref: https://github.com/python-attrs/attrs/pull/571/files\ +# #diff-85987f48f1258d9ee486e3191495582dR82 +default_role = 'any' + +# HTML theme +html_theme = 'furo' +html_logo = "images/logo.svg" + +html_theme_options = { + "sidebar_hide_name": True, + "light_css_variables": { + "color-brand-primary": "#336790", # "blue" + "color-brand-content": "#336790", + }, + "dark_css_variables": { + "color-brand-primary": "#E5B62F", # "yellow" + "color-brand-content": "#E5B62F", + }, +} + +# Redirect old docs so links and references in the ecosystem don't break +extensions += ['sphinx_reredirects'] +redirects = { + "userguide/keywords": "/deprecated/changed_keywords.html", + "userguide/commands": "/deprecated/commands.html", +} + +# Add support for inline tabs +extensions += ['sphinx_inline_tabs'] + +# Support for distutils + +# Ref: https://stackoverflow.com/a/30624034/595220 +nitpick_ignore = [ + ('c:func', 'SHGetSpecialFolderPath'), # ref to MS docs + ('envvar', 'DISTUTILS_DEBUG'), # undocumented + ('envvar', 'HOME'), # undocumented + ('envvar', 'PLAT'), # undocumented + ('py:attr', 'CCompiler.language_map'), # undocumented + ('py:attr', 'CCompiler.language_order'), # undocumented + ('py:class', 'distutils.dist.Distribution'), # undocumented + ('py:class', 'distutils.extension.Extension'), # undocumented + ('py:class', 'BorlandCCompiler'), # undocumented + ('py:class', 'CCompiler'), # undocumented + ('py:class', 'CygwinCCompiler'), # undocumented + ('py:class', 'distutils.dist.DistributionMetadata'), # undocumented + ('py:class', 'FileList'), # undocumented + ('py:class', 'IShellLink'), # ref to MS docs + ('py:class', 'MSVCCompiler'), # undocumented + ('py:class', 'OptionDummy'), # undocumented + ('py:class', 'UnixCCompiler'), # undocumented + ('py:exc', 'CompileError'), # undocumented + ('py:exc', 'DistutilsExecError'), # undocumented + ('py:exc', 'DistutilsFileError'), # undocumented + ('py:exc', 'LibError'), # undocumented + ('py:exc', 'LinkError'), # undocumented + ('py:exc', 'PreprocessError'), # undocumented + ('py:exc', 'setuptools.errors.PlatformError'), # sphinx cannot find it + ('py:func', 'distutils.CCompiler.new_compiler'), # undocumented + # undocumented: + ('py:func', 'distutils.dist.DistributionMetadata.read_pkg_file'), + ('py:func', 'distutils.file_util._copy_file_contents'), # undocumented + ('py:func', 'distutils.log.debug'), # undocumented + ('py:func', 'distutils.spawn.find_executable'), # undocumented + ('py:func', 'distutils.spawn.spawn'), # undocumented + # TODO: check https://docutils.rtfd.io in the future + ('py:mod', 'docutils'), # there's no Sphinx site documenting this +] + +# Allow linking objects on other Sphinx sites seamlessly: +intersphinx_mapping.update( + python=('https://docs.python.org/3', None), +) + +# Add support for the unreleased "next-version" change notes +extensions += ['sphinxcontrib.towncrier'] +# Extension needs a path from here to the towncrier config. +towncrier_draft_working_directory = '..' +# Avoid an empty section for unpublished changes. +towncrier_draft_include_empty = False + +extensions += ['jaraco.tidelift'] + +# Add icons (aka "favicons") to documentation +extensions += ['sphinx-favicon'] +html_static_path = ['images'] # should contain the folder with icons + +# Add support for nice Not Found 404 pages +extensions += ['notfound.extension'] + +# List of dicts with <link> HTML attributes +# static-file points to files in the html_static_path (href is computed) +favicons = [ + { # "Catch-all" goes first, otherwise some browsers will overwrite + "rel": "icon", + "type": "image/svg+xml", + "static-file": "logo-symbol-only.svg", + "sizes": "any" + }, + { # Version with thicker strokes for better visibility at smaller sizes + "rel": "icon", + "type": "image/svg+xml", + "static-file": "favicon.svg", + "sizes": "16x16 24x24 32x32 48x48" + }, + # rel="apple-touch-icon" does not support SVG yet +] diff --git a/docs/deprecated/changed_keywords.rst b/docs/deprecated/changed_keywords.rst new file mode 100644 index 00000000..7db372f2 --- /dev/null +++ b/docs/deprecated/changed_keywords.rst @@ -0,0 +1,112 @@ +New and Changed ``setup()`` Keywords +==================================== + +This document tracks historical differences between ``setuptools`` and +``distutils``. + +Since ``distutils`` was scheduled for removal from the standard library in +Python 3.12, and ``setuptools`` started its adoption, these differences became less +relevant. +Please check :doc:`/references/keywords` for a complete list of keyword +arguments that can be passed to the ``setuptools.setup()`` function and +a their full description. + +.. tab:: Supported by both ``distutils`` and ``setuptoools`` + + ``name`` string + + ``version`` string + + ``description`` string + + ``long_description`` string + + ``long_description_content_type`` string + + ``author`` string + + ``author_email`` string + + ``maintainer`` string + + ``maintainer_email`` string + + ``url`` string + + ``download_url`` string + + ``packages`` list + + ``py_modules`` list + + ``scripts`` list + + ``ext_package`` string + + ``ext_modules`` list + + ``classifiers`` list + + ``distclass`` Distribution subclass + + ``script_name`` string + + ``script_args`` list + + ``options`` dictionary + + ``license`` string + + ``license_file`` string **deprecated** + + ``license_files`` list + + ``keywords`` string or list + + ``platforms`` list + + ``cmdclass`` dictionary + + ``data_files`` list **deprecated** + + ``package_dir`` dictionary + + ``requires`` string or list **deprecated** + + ``obsoletes`` list **deprecated** + + ``provides`` list + +.. tab:: Added or changed by ``setuptoools`` + + ``include_package_data`` bool + + ``exclude_package_data`` dictionary + + ``package_data`` dictionary + + ``zip_safe`` bool + + ``install_requires`` string or list + + ``entry_points`` dictionary + + ``extras_require`` dictionary + + ``python_requires`` string + + ``setup_requires`` string or list **deprecated** + + ``dependency_links`` list **deprecated** + + ``namespace_packages`` list + + ``test_suite`` string or function **deprecated** + + ``tests_require`` string or list **deprecated** + + ``test_loader`` class **deprecated** + + ``eager_resources`` list + + ``project_urls`` dictionary diff --git a/docs/deprecated/commands.rst b/docs/deprecated/commands.rst new file mode 100644 index 00000000..d9d97a9e --- /dev/null +++ b/docs/deprecated/commands.rst @@ -0,0 +1,622 @@ +=============================== +Running ``setuptools`` commands +=============================== + +Historically, ``setuptools`` allowed running commands via a ``setup.py`` script +at the root of a Python project, as indicated in the examples below:: + + python setup.py --help + python setup.py --help-commands + python setup.py --version + python setup.py sdist + python setup.py bdist_wheel + +You could also run commands in other circumstances: + +* ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only):: + + python -c "from setuptools import setup; setup()" --help + +* ``distutils`` projects (with a ``setup.py`` importing ``distutils``):: + + python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop + +That is, you can simply list the normal setup commands and options following the quoted part. + +.. warning:: + While it is perfectly fine that users write ``setup.py`` files to configure + a package build (e.g. to specify binary extensions or customize commands), + on recent versions of ``setuptools``, running ``python setup.py`` directly + as a script is considered **deprecated**. This also means that users should + avoid running commands directly via ``python setup.py <command>``. + + If you want to create :term:`sdist <Source Distribution (or "sdist")>` or :term:`wheel` + distributions the recommendation is to use the command line tool provided by :pypi:`build`:: + + pip install build # needs to be installed first + + python -m build # builds both sdist and wheel + python -m build --sdist + python -m build --wheel + + Build will automatically download ``setuptools`` and build the package in an + isolated environment. You can also specify specific versions of + ``setuptools``, by setting the :doc:`build requirements in pyproject.toml + </build_meta>`. + + If you want to install a package, you can use :pypi:`pip` or :pypi:`installer`:: + + pip install /path/to/wheel/file.whl + pip install /path/to/sdist/file.tar.gz + pip install . # replacement for python setup.py install + pip install --editable . # replacement for python setup.py develop + + pip install installer # needs to be installed first + python -m installer /path/to/wheel/file.whl + +----------------- +Command Reference +----------------- + +.. _alias: + +``alias`` - Define shortcuts for commonly used commands +======================================================= + +Sometimes, you need to use the same commands over and over, but you can't +necessarily set them as defaults. For example, if you produce both development +snapshot releases and "stable" releases of a project, you may want to put +the distributions in different places, or use different ``egg_info`` tagging +options, etc. In these cases, it doesn't make sense to set the options in +a distutils configuration file, because the values of the options changed based +on what you're trying to do. + +Setuptools therefore allows you to define "aliases" - shortcut names for +an arbitrary string of commands and options, using ``setup.py alias aliasname +expansion``, where aliasname is the name of the new alias, and the remainder of +the command line supplies its expansion. For example, this command defines +a sitewide alias called "daily", that sets various ``egg_info`` tagging +options:: + + setup.py alias --global-config daily egg_info --tag-build=development + +Once the alias is defined, it can then be used with other setup commands, +e.g.:: + + setup.py daily bdist_egg # generate a daily-build .egg file + setup.py daily sdist # generate a daily-build source distro + setup.py daily sdist bdist_egg # generate both + +The above commands are interpreted as if the word ``daily`` were replaced with +``egg_info --tag-build=development``. + +Note that setuptools will expand each alias *at most once* in a given command +line. This serves two purposes. First, if you accidentally create an alias +loop, it will have no effect; you'll instead get an error message about an +unknown command. Second, it allows you to define an alias for a command, that +uses that command. For example, this (project-local) alias:: + + setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg + +redefines the ``bdist_egg`` command so that it always runs the ``rotate`` +command afterwards to delete all but the newest egg file. It doesn't loop +indefinitely on ``bdist_egg`` because the alias is only expanded once when +used. + +You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.:: + + setup.py alias --global-config --remove daily + +would delete the "daily" alias we defined above. + +Aliases can be defined on a project-specific, per-user, or sitewide basis. The +default is to define or remove a project-specific alias, but you can use any of +the `configuration file options`_ (listed under the `saveopts`_ command, below) +to determine which distutils configuration file an aliases will be added to +(or removed from). + +Note that if you omit the "expansion" argument to the ``alias`` command, +you'll get output showing that alias' current definition (and what +configuration file it's defined in). If you omit the alias name as well, +you'll get a listing of all current aliases along with their configuration +file locations. + + +``bdist_egg`` - Create a Python Egg for the project +=================================================== + +.. warning:: + **eggs** are deprecated in favor of wheels, and not supported by pip. + +This command generates a Python Egg (``.egg`` file) for the project. Python +Eggs are the preferred binary distribution format for EasyInstall, because they +are cross-platform (for "pure" packages), directly importable, and contain +project metadata including scripts and information about the project's +dependencies. They can be simply downloaded and added to ``sys.path`` +directly, or they can be placed in a directory on ``sys.path`` and then +automatically discovered by the egg runtime system. + +This command runs the `egg_info`_ command (if it hasn't already run) to update +the project's metadata (``.egg-info``) directory. If you have added any extra +metadata files to the ``.egg-info`` directory, those files will be included in +the new egg file's metadata directory, for use by the egg runtime system or by +any applications or frameworks that use that metadata. + +You won't usually need to specify any special options for this command; just +use ``bdist_egg`` and you're done. But there are a few options that may +be occasionally useful: + +``--dist-dir=DIR, -d DIR`` + Set the directory where the ``.egg`` file will be placed. If you don't + supply this, then the ``--dist-dir`` setting of the ``bdist`` command + will be used, which is usually a directory named ``dist`` in the project + directory. + +``--plat-name=PLATFORM, -p PLATFORM`` + Set the platform name string that will be embedded in the egg's filename + (assuming the egg contains C extensions). This can be used to override + the distutils default platform name with something more meaningful. Keep + in mind, however, that the egg runtime system expects to see eggs with + distutils platform names, so it may ignore or reject eggs with non-standard + platform names. Similarly, the EasyInstall program may ignore them when + searching web pages for download links. However, if you are + cross-compiling or doing some other unusual things, you might find a use + for this option. + +``--exclude-source-files`` + Don't include any modules' ``.py`` files in the egg, just compiled Python, + C, and data files. (Note that this doesn't affect any ``.py`` files in the + EGG-INFO directory or its subdirectories, since for example there may be + scripts with a ``.py`` extension which must still be retained.) We don't + recommend that you use this option except for packages that are being + bundled for proprietary end-user applications, or for "embedded" scenarios + where space is at an absolute premium. On the other hand, if your package + is going to be installed and used in compressed form, you might as well + exclude the source because Python's ``traceback`` module doesn't currently + understand how to display zipped source code anyway, or how to deal with + files that are in a different place from where their code was compiled. + +There are also some options you will probably never need, but which are there +because they were copied from similar ``bdist`` commands used as an example for +creating this one. They may be useful for testing and debugging, however, +which is why we kept them: + +``--keep-temp, -k`` + Keep the contents of the ``--bdist-dir`` tree around after creating the + ``.egg`` file. + +``--bdist-dir=DIR, -b DIR`` + Set the temporary directory for creating the distribution. The entire + contents of this directory are zipped to create the ``.egg`` file, after + running various installation commands to copy the package's modules, data, + and extensions here. + +``--skip-build`` + Skip doing any "build" commands; just go straight to the + install-and-compress phases. + + +.. _develop: + +``develop`` - Deploy the project source in "Development Mode" +============================================================= + +This command allows you to deploy your project's source for use in one or more +"staging areas" where it will be available for importing. This deployment is +done in such a way that changes to the project source are immediately available +in the staging area(s), without needing to run a build or install step after +each change. + +The ``develop`` command works by creating an ``.egg-link`` file (named for the +project) in the given staging area. If the staging area is Python's +``site-packages`` directory, it also updates an ``easy-install.pth`` file so +that the project is on ``sys.path`` by default for all programs run using that +Python installation. + +The ``develop`` command also installs wrapper scripts in the staging area (or +a separate directory, as specified) that will ensure the project's dependencies +are available on ``sys.path`` before running the project's source scripts. +And, it ensures that any missing project dependencies are available in the +staging area, by downloading and installing them if necessary. + +Last, but not least, the ``develop`` command invokes the ``build_ext -i`` +command to ensure any C extensions in the project have been built and are +up-to-date, and the ``egg_info`` command to ensure the project's metadata is +updated (so that the runtime and wrappers know what the project's dependencies +are). If you make any changes to the project's setup script or C extensions, +you should rerun the ``develop`` command against all relevant staging areas to +keep the project's scripts, metadata and extensions up-to-date. Most other +kinds of changes to your project should not require any build operations or +rerunning ``develop``, but keep in mind that even minor changes to the setup +script (e.g. changing an entry point definition) require you to re-run the +``develop`` or ``test`` commands to keep the distribution updated. + +Here are some of the options that the ``develop`` command accepts. Note that +they affect the project's dependencies as well as the project itself, so if you +have dependencies that need to be installed and you use ``--exclude-scripts`` +(for example), the dependencies' scripts will not be installed either! For +this reason, you may want to use pip to install the project's dependencies +before using the ``develop`` command, if you need finer control over the +installation options for dependencies. + +``--uninstall, -u`` + Un-deploy the current project. You may use the ``--install-dir`` or ``-d`` + option to designate the staging area. The created ``.egg-link`` file will + be removed, if present and it is still pointing to the project directory. + The project directory will be removed from ``easy-install.pth`` if the + staging area is Python's ``site-packages`` directory. + + Note that this option currently does *not* uninstall script wrappers! You + must uninstall them yourself, or overwrite them by using pip to install a + different version of the package. You can also avoid installing script + wrappers in the first place, if you use the ``--exclude-scripts`` (aka + ``-x``) option when you run ``develop`` to deploy the project. + +``--multi-version, -m`` + "Multi-version" mode. Specifying this option prevents ``develop`` from + adding an ``easy-install.pth`` entry for the project(s) being deployed, and + if an entry for any version of a project already exists, the entry will be + removed upon successful deployment. In multi-version mode, no specific + version of the package is available for importing, unless you use + ``pkg_resources.require()`` to put it on ``sys.path``, or you are running + a wrapper script generated by ``setuptools``. (In which case the wrapper + script calls ``require()`` for you.) + + Note that if you install to a directory other than ``site-packages``, + this option is automatically in effect, because ``.pth`` files can only be + used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use + the ``--install-dir`` or ``-d`` option (or they are set via configuration + file(s)) your project and its dependencies will be deployed in multi- + version mode. + +``--install-dir=DIR, -d DIR`` + Set the installation directory (staging area). If this option is not + directly specified on the command line or in a distutils configuration + file, the distutils default installation location is used. Normally, this + will be the ``site-packages`` directory, but if you are using distutils + configuration files, setting things like ``prefix`` or ``install_lib``, + then those settings are taken into account when computing the default + staging area. + +``--script-dir=DIR, -s DIR`` + Set the script installation directory. If you don't supply this option + (via the command line or a configuration file), but you *have* supplied + an ``--install-dir`` (via command line or config file), then this option + defaults to the same directory, so that the scripts will be able to find + their associated package installation. Otherwise, this setting defaults + to the location where the distutils would normally install scripts, taking + any distutils configuration file settings into account. + +``--exclude-scripts, -x`` + Don't deploy script wrappers. This is useful if you don't want to disturb + existing versions of the scripts in the staging area. + +``--always-copy, -a`` + Copy all needed distributions to the staging area, even if they + are already present in another directory on ``sys.path``. By default, if + a requirement can be met using a distribution that is already available in + a directory on ``sys.path``, it will not be copied to the staging area. + +``--egg-path=DIR`` + Force the generated ``.egg-link`` file to use a specified relative path + to the source directory. This can be useful in circumstances where your + installation directory is being shared by code running under multiple + platforms (e.g. Mac and Windows) which have different absolute locations + for the code under development, but the same *relative* locations with + respect to the installation directory. If you use this option when + installing, you must supply the same relative path when uninstalling. + +In addition to the above options, the ``develop`` command also accepts all of +the same options accepted by ``easy_install``. If you've configured any +``easy_install`` settings in your ``setup.cfg`` (or other distutils config +files), the ``develop`` command will use them as defaults, unless you override +them in a ``[develop]`` section or on the command line. + + +.. _egg_info: + +``egg_info`` - Create egg metadata and set build tags +===================================================== + +This command performs two operations: it updates a project's ``.egg-info`` +metadata directory (used by the ``bdist_egg``, ``develop``, and ``test`` +commands), and it allows you to temporarily change a project's version string, +to support "daily builds" or "snapshot" releases. It is run automatically by +the ``sdist``, ``bdist_egg``, ``develop``, and ``test`` commands in order to +update the project's metadata, but you can also specify it explicitly in order +to temporarily change the project's version string while executing other +commands. (It also generates the ``.egg-info/SOURCES.txt`` manifest file, which +is used when you are building source distributions.) + +In addition to writing the core egg metadata defined by ``setuptools`` and +required by ``pkg_resources``, this command can be extended to write other +metadata files as well, by defining entry points in the ``egg_info.writers`` +group. See the section on :ref:`Adding new EGG-INFO Files` below for more details. +Note that using additional metadata writers may require you to include a +``setup_requires`` argument to ``setup()`` in order to ensure that the desired +writers are available on ``sys.path``. + + +Release Tagging Options +----------------------- + +The following options can be used to modify the project's version string for +all remaining commands on the setup command line. The options are processed +in the order shown, so if you use more than one, the requested tags will be +added in the following order: + +``--tag-build=NAME, -b NAME`` + Append NAME to the project's version string. Due to the way setuptools + processes "pre-release" version suffixes beginning with the letters "a" + through "e" (like "alpha", "beta", and "candidate"), you will usually want + to use a tag like ".build" or ".dev", as this will cause the version number + to be considered *lower* than the project's default version. (If you + want to make the version number *higher* than the default version, you can + always leave off --tag-build and then use one or both of the following + options.) + + If you have a default build tag set in your ``setup.cfg``, you can suppress + it on the command line using ``-b ""`` or ``--tag-build=""`` as an argument + to the ``egg_info`` command. + +``--tag-date, -d`` + Add a date stamp of the form "-YYYYMMDD" (e.g. "-20050528") to the + project's version number. + +``--no-date, -D`` + Don't include a date stamp in the version number. This option is included + so you can override a default setting in ``setup.cfg``. + + +(Note: Because these options modify the version number used for source and +binary distributions of your project, you should first make sure that you know +how the resulting version numbers will be interpreted by automated tools +like pip. See the section above on :ref:`Specifying Your Project's Version` for an +explanation of pre- and post-release tags, as well as tips on how to choose and +verify a versioning scheme for your project.) + +For advanced uses, there is one other option that can be set, to change the +location of the project's ``.egg-info`` directory. Commands that need to find +the project's source directory or metadata should get it from this setting: + + +Other ``egg_info`` Options +-------------------------- + +``--egg-base=SOURCEDIR, -e SOURCEDIR`` + Specify the directory that should contain the .egg-info directory. This + should normally be the root of your project's source tree (which is not + necessarily the same as your project directory; some projects use a ``src`` + or ``lib`` subdirectory as the source root). You should not normally need + to specify this directory, as it is normally determined from the + ``package_dir`` argument to the ``setup()`` function, if any. If there is + no ``package_dir`` set, this option defaults to the current directory. + + +``egg_info`` Examples +--------------------- + +Creating a dated "nightly build" snapshot egg:: + + setup.py egg_info --tag-date --tag-build=DEV bdist_egg + +Creating a release with no version tags, even if some default tags are +specified in ``setup.cfg``:: + + setup.py egg_info -RDb "" sdist bdist_egg + +(Notice that ``egg_info`` must always appear on the command line *before* any +commands that you want the version changes to apply to.) + +.. _rotate: + +``rotate`` - Delete outdated distribution files +=============================================== + +As you develop new versions of your project, your distribution (``dist``) +directory will gradually fill up with older source and/or binary distribution +files. The ``rotate`` command lets you automatically clean these up, keeping +only the N most-recently modified files matching a given pattern. + +``--match=PATTERNLIST, -m PATTERNLIST`` + Comma-separated list of glob patterns to match. This option is *required*. + The project name and ``-*`` is prepended to the supplied patterns, in order + to match only distributions belonging to the current project (in case you + have a shared distribution directory for multiple projects). Typically, + you will use a glob pattern like ``.zip`` or ``.egg`` to match files of + the specified type. Note that each supplied pattern is treated as a + distinct group of files for purposes of selecting files to delete. + +``--keep=COUNT, -k COUNT`` + Number of matching distributions to keep. For each group of files + identified by a pattern specified with the ``--match`` option, delete all + but the COUNT most-recently-modified files in that group. This option is + *required*. + +``--dist-dir=DIR, -d DIR`` + Directory where the distributions are. This defaults to the value of the + ``bdist`` command's ``--dist-dir`` option, which will usually be the + project's ``dist`` subdirectory. + +**Example 1**: Delete all .tar.gz files from the distribution directory, except +for the 3 most recently modified ones:: + + setup.py rotate --match=.tar.gz --keep=3 + +**Example 2**: Delete all Python 2.3 or Python 2.4 eggs from the distribution +directory, except the most recently modified one for each Python version:: + + setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1 + + +.. _saveopts: + +``saveopts`` - Save used options to a configuration file +======================================================== + +Finding and editing ``distutils`` configuration files can be a pain, especially +since you also have to translate the configuration options from command-line +form to the proper configuration file format. You can avoid these hassles by +using the ``saveopts`` command. Just add it to the command line to save the +options you used. For example, this command builds the project using +the ``mingw32`` C compiler, then saves the --compiler setting as the default +for future builds (even those run implicitly by the ``install`` command):: + + setup.py build --compiler=mingw32 saveopts + +The ``saveopts`` command saves all options for every command specified on the +command line to the project's local ``setup.cfg`` file, unless you use one of +the `configuration file options`_ to change where the options are saved. For +example, this command does the same as above, but saves the compiler setting +to the site-wide (global) distutils configuration:: + + setup.py build --compiler=mingw32 saveopts -g + +Note that it doesn't matter where you place the ``saveopts`` command on the +command line; it will still save all the options specified for all commands. +For example, this is another valid way to spell the last example:: + + setup.py saveopts -g build --compiler=mingw32 + +Note, however, that all of the commands specified are always run, regardless of +where ``saveopts`` is placed on the command line. + + +Configuration File Options +-------------------------- + +Normally, settings such as options and aliases are saved to the project's +local ``setup.cfg`` file. But you can override this and save them to the +global or per-user configuration files, or to a manually-specified filename. + +``--global-config, -g`` + Save settings to the global ``distutils.cfg`` file inside the ``distutils`` + package directory. You must have write access to that directory to use + this option. You also can't combine this option with ``-u`` or ``-f``. + +``--user-config, -u`` + Save settings to the current user's ``~/.pydistutils.cfg`` (POSIX) or + ``$HOME/pydistutils.cfg`` (Windows) file. You can't combine this option + with ``-g`` or ``-f``. + +``--filename=FILENAME, -f FILENAME`` + Save settings to the specified configuration file to use. You can't + combine this option with ``-g`` or ``-u``. Note that if you specify a + non-standard filename, the ``distutils`` and ``setuptools`` will not + use the file's contents. This option is mainly included for use in + testing. + +These options are used by other ``setuptools`` commands that modify +configuration files, such as the `alias`_ and `setopt`_ commands. + + +.. _setopt: + +``setopt`` - Set a distutils or setuptools option in a config file +================================================================== + +This command is mainly for use by scripts, but it can also be used as a quick +and dirty way to change a distutils configuration option without having to +remember what file the options are in and then open an editor. + +**Example 1**. Set the default C compiler to ``mingw32`` (using long option +names):: + + setup.py setopt --command=build --option=compiler --set-value=mingw32 + +**Example 2**. Remove any setting for the distutils default package +installation directory (short option names):: + + setup.py setopt -c install -o install_lib -r + + +Options for the ``setopt`` command: + +``--command=COMMAND, -c COMMAND`` + Command to set the option for. This option is required. + +``--option=OPTION, -o OPTION`` + The name of the option to set. This option is required. + +``--set-value=VALUE, -s VALUE`` + The value to set the option to. Not needed if ``-r`` or ``--remove`` is + set. + +``--remove, -r`` + Remove (unset) the option, instead of setting it. + +In addition to the above options, you may use any of the `configuration file +options`_ (listed under the `saveopts`_ command, above) to determine which +distutils configuration file the option will be added to (or removed from). + + +.. _test: + +``test`` - Build package and run a unittest suite +================================================= + +.. warning:: + ``test`` is deprecated and will be removed in a future version. Users + looking for a generic test entry point independent of test runner are + encouraged to use `tox <https://tox.readthedocs.io>`_. + +When doing test-driven development, or running automated builds that need +testing before they are deployed for downloading or use, it's often useful +to be able to run a project's unit tests without actually deploying the project +anywhere, even using the ``develop`` command. The ``test`` command runs a +project's unit tests without actually deploying it, by temporarily putting the +project's source on ``sys.path``, after first running ``build_ext -i`` and +``egg_info`` to ensure that any C extensions and project metadata are +up-to-date. + +To use this command, your project's tests must be wrapped in a ``unittest`` +test suite by either a function, a ``TestCase`` class or method, or a module +or package containing ``TestCase`` classes. If the named suite is a module, +and the module has an ``additional_tests()`` function, it is called and the +result (which must be a ``unittest.TestSuite``) is added to the tests to be +run. If the named suite is a package, any submodules and subpackages are +recursively added to the overall test suite. (Note: if your project specifies +a ``test_loader``, the rules for processing the chosen ``test_suite`` may +differ; see the :ref:`test_loader <test_loader>` documentation for more details.) + +Note that many test systems including ``doctest`` support wrapping their +non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test +package that does not support this, we suggest you encourage its developers to +implement test suite support, as this is a convenient and standard way to +aggregate a collection of tests to be run under a common test harness. + +By default, tests will be run in the "verbose" mode of the ``unittest`` +package's text test runner, but you can get the "quiet" mode (just dots) if +you supply the ``-q`` or ``--quiet`` option, either as a global option to +the setup script (e.g. ``setup.py -q test``) or as an option for the ``test`` +command itself (e.g. ``setup.py test -q``). There is one other option +available: + +``--test-suite=NAME, -s NAME`` + Specify the test suite (or module, class, or method) to be run + (e.g. ``some_module.test_suite``). The default for this option can be + set by giving a ``test_suite`` argument to the ``setup()`` function, e.g.:: + + setup( + # ... + test_suite="my_package.tests.test_all" + ) + + If you did not set a ``test_suite`` in your ``setup()`` call, and do not + provide a ``--test-suite`` option, an error will occur. + +New in 41.5.0: Deprecated the test command. + + +.. _upload: + +``upload`` - Upload source and/or egg distributions to PyPI +=========================================================== + +The ``upload`` command was deprecated in version 40.0 and removed in version +42.0. Use `twine <https://pypi.org/p/twine>`_ instead. + +For more information on the current best practices in uploading your packages +to PyPI, see the Python Packaging User Guide's "Packaging Python Projects" +tutorial specifically the section on `uploading the distribution archives +<https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives>`_. diff --git a/docs/deprecated/dependency_links.rst b/docs/deprecated/dependency_links.rst new file mode 100644 index 00000000..70e1a78e --- /dev/null +++ b/docs/deprecated/dependency_links.rst @@ -0,0 +1,77 @@ +Specifying dependencies that aren't in PyPI via ``dependency_links`` +==================================================================== + +.. warning:: + Dependency links support has been dropped by pip starting with version + 19.0 (released 2019-01-22). + +If your project depends on packages that don't exist on PyPI, you *may* still be +able to depend on them if they are available for download as: + +- an egg, in the standard distutils ``sdist`` format, +- a single ``.py`` file, or +- a VCS repository (Subversion, Mercurial, or Git). + +You need to add some URLs to the ``dependency_links`` argument to ``setup()``. + +The URLs must be either: + +1. direct download URLs, +2. the URLs of web pages that contain direct download links, or +3. the repository's URL + +In general, it's better to link to web pages, because it is usually less +complex to update a web page than to release a new version of your project. +You can also use a SourceForge ``showfiles.php`` link in the case where a +package you depend on is distributed via SourceForge. + +If you depend on a package that's distributed as a single ``.py`` file, you +must include an ``"#egg=project-version"`` suffix to the URL, to give a project +name and version number. (Be sure to escape any dashes in the name or version +by replacing them with underscores.) EasyInstall will recognize this suffix +and automatically create a trivial ``setup.py`` to wrap the single ``.py`` file +as an egg. + +In the case of a VCS checkout, you should also append ``#egg=project-version`` +in order to identify for what package that checkout should be used. You can +append ``@REV`` to the URL's path (before the fragment) to specify a revision. +Additionally, you can also force the VCS being used by prepending the URL with +a certain prefix. Currently available are: + +- ``svn+URL`` for Subversion, +- ``git+URL`` for Git, and +- ``hg+URL`` for Mercurial + +A more complete example would be: + + ``vcs+proto://host/path@revision#egg=project-version`` + +Be careful with the version. It should match the one inside the project files. +If you want to disregard the version, you have to omit it both in the +``requires`` and in the URL's fragment. + +This will do a checkout (or a clone, in Git and Mercurial parlance) to a +temporary folder and run ``setup.py bdist_egg``. + +The ``dependency_links`` option takes the form of a list of URL strings. For +example, this will cause a search of the specified page for eggs or source +distributions, if the package's dependencies aren't already installed: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + #... + dependency_links = http://peak.telecommunity.com/snapshots/ + +.. tab:: setup.py + + .. code-block:: python + + setup( + ..., + dependency_links=[ + "http://peak.telecommunity.com/snapshots/", + ], + ) diff --git a/docs/deprecated/distutils-legacy.rst b/docs/deprecated/distutils-legacy.rst new file mode 100644 index 00000000..63c8ff07 --- /dev/null +++ b/docs/deprecated/distutils-legacy.rst @@ -0,0 +1,45 @@ +Porting from Distutils +====================== + +Setuptools and the PyPA have a `stated goal <https://github.com/pypa/packaging-problems/issues/127>`_ to make Setuptools the reference API for distutils. + +Since the 60.0.0 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is enabled by default. To disable the use of this copy of distutils when invoking setuptools, set the environment variable: + + SETUPTOOLS_USE_DISTUTILS=stdlib + +.. warning:: + Please note that this also affects how ``distutils.cfg`` files inside stdlib's ``distutils`` + package directory are processed. + Unless ``SETUPTOOLS_USE_DISTUTILS=stdlib``, they will have no effect on the build process. + + You can still use a global user config file, ``~/.pydistutils.cfg`` (POSIX) or ``%USERPROFILE%/pydistutils.cfg`` (Windows), + or use the environment variable :doc:`DIST_EXTRA_CONFIG <deprecated/distutils/configfile>` to point to another + supplementary configuration file. + + +Prefer Setuptools +----------------- + +As Distutils is deprecated, any usage of functions or objects from distutils is similarly discouraged, and Setuptools aims to replace or deprecate all such uses. This section describes the recommended replacements. + +``distutils.core.setup`` → ``setuptools.setup`` + +``distutils.cmd.Command`` → ``setuptools.Command`` + +``distutils.command.{build_clib,build_ext,build_py,sdist}`` → ``setuptools.command.*`` + +``distutils.log`` → :mod:`logging` (standard library) + +``distutils.version.*`` → :doc:`packaging.version.* <packaging:version>` + +``distutils.errors.*`` → ``setuptools.errors.*`` [#errors]_ + + +Migration advice is also provided by :pep:`PEP 632 <632#migration-advice>`. + +If a project relies on uses of ``distutils`` that do not have a suitable replacement above, please search the `Setuptools issue tracker <https://github.com/pypa/setuptools/issues/>`_ and file a request, describing the use-case so that Setuptools' maintainers can investigate. Please provide enough detail to help the maintainers understand how distutils is used, what value it provides, and why that behavior should be supported. + + +.. [#errors] Please notice errors related to the command line usage of + ``setup.py``, such as ``DistutilsArgError``, are intentionally not exposed + by setuptools, since this is considered a deprecated practice. diff --git a/docs/deprecated/distutils/_setuptools_disclaimer.rst b/docs/deprecated/distutils/_setuptools_disclaimer.rst new file mode 100644 index 00000000..628c2e4f --- /dev/null +++ b/docs/deprecated/distutils/_setuptools_disclaimer.rst @@ -0,0 +1,5 @@ +.. note:: + + This document is being retained solely until the ``setuptools`` documentation + at https://setuptools.pypa.io/en/latest/setuptools.html + independently covers all of the relevant information currently included here. diff --git a/docs/deprecated/distutils/apiref.rst b/docs/deprecated/distutils/apiref.rst new file mode 100644 index 00000000..278471a2 --- /dev/null +++ b/docs/deprecated/distutils/apiref.rst @@ -0,0 +1,2016 @@ +.. _api-reference: + +************* +API Reference +************* + +.. seealso:: + + `New and changed setup.py arguments in setuptools`_ + The ``setuptools`` project adds new capabilities to the ``setup`` function + and other APIs, makes the API consistent across different Python versions, + and is hence recommended over using ``distutils`` directly. + +.. _New and changed setup.py arguments in setuptools: https://setuptools.pypa.io/en/latest/setuptools.html#new-and-changed-setup-keywords + +.. include:: ./_setuptools_disclaimer.rst + +:mod:`distutils.core` --- Core Distutils functionality +====================================================== + +.. module:: distutils.core + :synopsis: The core Distutils functionality + + +The :mod:`distutils.core` module is the only module that needs to be installed +to use the Distutils. It provides the :func:`setup` (which is called from the +setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +:class:`distutils.cmd.Command` class. + + +.. function:: setup(arguments) + + The basic do-everything function that does most everything you could ever ask + for from a Distutils method. + + The setup function takes a large number of arguments. These are laid out in the + following table. + + .. tabularcolumns:: |l|L|L| + + +--------------------+--------------------------------+-------------------------------------------------------------+ + | argument name | value | type | + +====================+================================+=============================================================+ + | *name* | The name of the package | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *version* | The version number of the | a string | + | | package; see | | + | | :mod:`distutils.version` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *description* | A single line describing the | a string | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *long_description* | Longer description of the | a string | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *author* | The name of the package author | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *author_email* | The email address of the | a string | + | | package author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *maintainer* | The name of the current | a string | + | | maintainer, if different from | | + | | the author. Note that if | | + | | the maintainer is provided, | | + | | distutils will use it as the | | + | | author in :file:`PKG-INFO` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *maintainer_email* | The email address of the | a string | + | | current maintainer, if | | + | | different from the author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *url* | A URL for the package | a string | + | | (homepage) | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *download_url* | A URL to download the package | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *packages* | A list of Python packages that | a list of strings | + | | distutils will manipulate | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *py_modules* | A list of Python modules that | a list of strings | + | | distutils will manipulate | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *scripts* | A list of standalone script | a list of strings | + | | files to be built and | | + | | installed | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *ext_modules* | A list of Python extensions to | a list of instances of | + | | be built | :class:`distutils.core.Extension` | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | + | | package | <https://pypi.org/classifiers>`_. | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *distclass* | the :class:`Distribution` | a subclass of | + | | class to use | :class:`distutils.core.Distribution` | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *script_name* | The name of the setup.py | a string | + | | script - defaults to | | + | | ``sys.argv[0]`` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *script_args* | Arguments to supply to the | a list of strings | + | | setup script | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *options* | default options for the setup | a dictionary | + | | script | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *license* | The license for the package | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string | + | | :pep:`314` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *platforms* | | a list of strings or a comma-separated string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *cmdclass* | A mapping of command names to | a dictionary | + | | :class:`Command` subclasses | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *data_files* | A list of data files to | a list | + | | install | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *package_dir* | A mapping of package to | a dictionary | + | | directory names | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + + + +.. function:: run_setup(script_name[, script_args=None, stop_after='run']) + + Run a setup script in a somewhat controlled environment, and return the + :class:`distutils.dist.Distribution` instance that drives things. This is + useful if you need to find out the distribution meta-data (passed as keyword + args from *script* to :func:`setup`), or the contents of the config files or + command-line. + + *script_name* is a file that will be read and run with :func:`exec`. ``sys.argv[0]`` + will be replaced with *script* for the duration of the call. *script_args* is a + list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args* + for the duration of the call. + + *stop_after* tells :func:`setup` when to stop processing; possible values: + + .. tabularcolumns:: |l|L| + + +---------------+---------------------------------------------+ + | value | description | + +===============+=============================================+ + | *init* | Stop after the :class:`Distribution` | + | | instance has been created and populated | + | | with the keyword arguments to :func:`setup` | + +---------------+---------------------------------------------+ + | *config* | Stop after config files have been parsed | + | | (and their data stored in the | + | | :class:`Distribution` instance) | + +---------------+---------------------------------------------+ + | *commandline* | Stop after the command-line | + | | (``sys.argv[1:]`` or *script_args*) have | + | | been parsed (and the data stored in the | + | | :class:`Distribution` instance.) | + +---------------+---------------------------------------------+ + | *run* | Stop after all commands have been run (the | + | | same as if :func:`setup` had been called | + | | in the usual way). This is the default | + | | value. | + +---------------+---------------------------------------------+ + +In addition, the :mod:`distutils.core` module exposed a number of classes that +live elsewhere. + +* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` + +* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` + +* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` + +A short description of each of these follows, but see the relevant module for +the full reference. + + +.. class:: Extension + + The Extension class describes a single C or C++ extension module in a setup + script. It accepts the following keyword arguments in its constructor: + + .. tabularcolumns:: |l|L|l| + + +------------------------+--------------------------------+---------------------------+ + | argument name | value | type | + +========================+================================+===========================+ + | *name* | the full name of the | a string | + | | extension, including any | | + | | packages --- ie. *not* a | | + | | filename or pathname, but | | + | | Python dotted name | | + +------------------------+--------------------------------+---------------------------+ + | *sources* | list of source filenames, | a list of strings | + | | relative to the distribution | | + | | root (where the setup script | | + | | lives), in Unix form | | + | | (slash-separated) for | | + | | portability. | | + | | Source files may be C, C++, | | + | | SWIG (.i), platform-specific | | + | | resource files, or whatever | | + | | else is recognized by the | | + | | :command:`build_ext` command | | + | | as source for a Python | | + | | extension. | | + +------------------------+--------------------------------+---------------------------+ + | *include_dirs* | list of directories to search | a list of strings | + | | for C/C++ header files (in | | + | | Unix form for portability) | | + +------------------------+--------------------------------+---------------------------+ + | *define_macros* | list of macros to define; each | a list of tuples | + | | macro is defined using a | | + | | 2-tuple ``(name, value)``, | | + | | where *value* is | | + | | either the string to define it | | + | | to or ``None`` to define it | | + | | without a particular value | | + | | (equivalent of ``#define FOO`` | | + | | in source or :option:`!-DFOO` | | + | | on Unix C compiler command | | + | | line) | | + +------------------------+--------------------------------+---------------------------+ + | *undef_macros* | list of macros to undefine | a list of strings | + | | explicitly | | + +------------------------+--------------------------------+---------------------------+ + | *library_dirs* | list of directories to search | a list of strings | + | | for C/C++ libraries at link | | + | | time | | + +------------------------+--------------------------------+---------------------------+ + | *libraries* | list of library names (not | a list of strings | + | | filenames or paths) to link | | + | | against | | + +------------------------+--------------------------------+---------------------------+ + | *runtime_library_dirs* | list of directories to search | a list of strings | + | | for C/C++ libraries at run | | + | | time (for shared extensions, | | + | | this is when the extension is | | + | | loaded) | | + +------------------------+--------------------------------+---------------------------+ + | *extra_objects* | list of extra files to link | a list of strings | + | | with (eg. object files not | | + | | implied by 'sources', static | | + | | library that must be | | + | | explicitly specified, binary | | + | | resource files, etc.) | | + +------------------------+--------------------------------+---------------------------+ + | *extra_compile_args* | any extra platform- and | a list of strings | + | | compiler-specific information | | + | | to use when compiling the | | + | | source files in 'sources'. For | | + | | platforms and compilers where | | + | | a command line makes sense, | | + | | this is typically a list of | | + | | command-line arguments, but | | + | | for other platforms it could | | + | | be anything. | | + +------------------------+--------------------------------+---------------------------+ + | *extra_link_args* | any extra platform- and | a list of strings | + | | compiler-specific information | | + | | to use when linking object | | + | | files together to create the | | + | | extension (or to create a new | | + | | static Python interpreter). | | + | | Similar interpretation as for | | + | | 'extra_compile_args'. | | + +------------------------+--------------------------------+---------------------------+ + | *export_symbols* | list of symbols to be exported | a list of strings | + | | from a shared extension. Not | | + | | used on all platforms, and not | | + | | generally necessary for Python | | + | | extensions, which typically | | + | | export exactly one symbol: | | + | | ``init`` + extension_name. | | + +------------------------+--------------------------------+---------------------------+ + | *depends* | list of files that the | a list of strings | + | | extension depends on | | + +------------------------+--------------------------------+---------------------------+ + | *language* | extension language (i.e. | a string | + | | ``'c'``, ``'c++'``, | | + | | ``'objc'``). Will be detected | | + | | from the source extensions if | | + | | not provided. | | + +------------------------+--------------------------------+---------------------------+ + | *optional* | specifies that a build failure | a boolean | + | | in the extension should not | | + | | abort the build process, but | | + | | simply skip the extension. | | + +------------------------+--------------------------------+---------------------------+ + + .. versionchanged:: 3.8 + + On Unix, C extensions are no longer linked to libpython except on + Android and Cygwin. + + +.. class:: Distribution + + A :class:`Distribution` describes how to build, install and package up a Python + software package. + + See the :func:`setup` function for a list of keyword arguments accepted by the + Distribution constructor. :func:`setup` creates a Distribution instance. + + .. versionchanged:: 3.7 + :class:`~distutils.core.Distribution` now warns if ``classifiers``, + ``keywords`` and ``platforms`` fields are not specified as a list or + a string. + +.. class:: Command + + A :class:`Command` class (or rather, an instance of one of its subclasses) + implement a single distutils command. + + +:mod:`distutils.ccompiler` --- CCompiler base class +=================================================== + +.. module:: distutils.ccompiler + :synopsis: Abstract CCompiler class + + +This module provides the abstract base class for the :class:`CCompiler` +classes. A :class:`CCompiler` instance can be used for all the compile and +link steps needed to build a single project. Methods are provided to set +options for the compiler --- macro definitions, include directories, link path, +libraries and the like. + +This module provides the following functions. + + +.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries) + + Generate linker options for searching library directories and linking with + specific libraries. *libraries* and *library_dirs* are, respectively, lists of + library names (not filenames!) and search directories. Returns a list of + command-line options suitable for use with some compiler (depending on the two + format strings passed in). + + +.. function:: gen_preprocess_options(macros, include_dirs) + + Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as + used by at least two types of compilers: the typical Unix compiler and Visual + C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` + means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define + (:option:`!-D`) macro *name* to *value*. *include_dirs* is just a list of + directory names to be added to the header file search path (:option:`!-I`). + Returns a list of command-line options suitable for either Unix compilers or + Visual C++. + + +.. function:: get_default_compiler(osname, platform) + + Determine the default compiler to use for the given platform. + + *osname* should be one of the standard Python OS names (i.e. the ones returned + by ``os.name``) and *platform* the common value returned by ``sys.platform`` for + the platform in question. + + The default values are ``os.name`` and ``sys.platform`` in case the parameters + are not given. + + +.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0) + + Factory function to generate an instance of some CCompiler subclass for the + supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg. + ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for + that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the + default compilers are "traditional Unix interface" (:class:`UnixCCompiler` + class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly + possible to ask for a Unix compiler object under Windows, and a Microsoft + compiler object under Unix---if you supply a value for *compiler*, *plat* is + ignored. + + .. % Is the posix/nt only thing still true? Mac OS X seems to work, and + .. % returns a UnixCCompiler instance. How to document this... hmm. + + +.. function:: show_compilers() + + Print list of available compilers (used by the :option:`!--help-compiler` options + to :command:`build`, :command:`build_ext`, :command:`build_clib`). + + +.. class:: CCompiler([verbose=0, dry_run=0, force=0]) + + The abstract base class :class:`CCompiler` defines the interface that must be + implemented by real compiler classes. The class also has some utility methods + used by several compiler classes. + + The basic idea behind a compiler abstraction class is that each instance can be + used for all the compile/link steps in building a single project. Thus, + attributes common to all of those compile and link steps --- include + directories, macros to define, libraries to link against, etc. --- are + attributes of the compiler instance. To allow for variability in how individual + files are treated, most of those attributes may be varied on a per-compilation + or per-link basis. + + The constructor for each subclass creates an instance of the Compiler object. + Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the + steps) and *force* (rebuild everything, regardless of dependencies). All of + these flags default to ``0`` (off). Note that you probably don't want to + instantiate :class:`CCompiler` or one of its subclasses directly - use the + :func:`distutils.CCompiler.new_compiler` factory function instead. + + The following methods allow you to manually alter compiler options for the + instance of the Compiler class. + + + .. method:: CCompiler.add_include_dir(dir) + + Add *dir* to the list of directories that will be searched for header files. + The compiler is instructed to search directories in the order in which they are + supplied by successive calls to :meth:`add_include_dir`. + + + .. method:: CCompiler.set_include_dirs(dirs) + + Set the list of directories that will be searched to *dirs* (a list of strings). + Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to + :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`. + This does not affect any list of standard include directories that the compiler + may search by default. + + + .. method:: CCompiler.add_library(libname) + + Add *libname* to the list of libraries that will be included in all links driven + by this compiler object. Note that *libname* should \*not\* be the name of a + file containing a library, but the name of the library itself: the actual + filename will be inferred by the linker, the compiler, or the compiler class + (depending on the platform). + + The linker will be instructed to link against libraries in the order they were + supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly + valid to duplicate library names; the linker will be instructed to link against + libraries as many times as they are mentioned. + + + .. method:: CCompiler.set_libraries(libnames) + + Set the list of libraries to be included in all links driven by this compiler + object to *libnames* (a list of strings). This does not affect any standard + system libraries that the linker may include by default. + + + .. method:: CCompiler.add_library_dir(dir) + + Add *dir* to the list of directories that will be searched for libraries + specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be + instructed to search for libraries in the order they are supplied to + :meth:`add_library_dir` and/or :meth:`set_library_dirs`. + + + .. method:: CCompiler.set_library_dirs(dirs) + + Set the list of library search directories to *dirs* (a list of strings). This + does not affect any standard library search path that the linker may search by + default. + + + .. method:: CCompiler.add_runtime_library_dir(dir) + + Add *dir* to the list of directories that will be searched for shared libraries + at runtime. + + + .. method:: CCompiler.set_runtime_library_dirs(dirs) + + Set the list of directories to search for shared libraries at runtime to *dirs* + (a list of strings). This does not affect any standard search path that the + runtime linker may search by default. + + + .. method:: CCompiler.define_macro(name[, value=None]) + + Define a preprocessor macro for all compilations driven by this compiler object. + The optional parameter *value* should be a string; if it is not supplied, then + the macro will be defined without an explicit value and the exact outcome + depends on the compiler used. + + .. XXX true? does ANSI say anything about this? + + + .. method:: CCompiler.undefine_macro(name) + + Undefine a preprocessor macro for all compilations driven by this compiler + object. If the same macro is defined by :meth:`define_macro` and + undefined by :meth:`undefine_macro` the last call takes precedence + (including multiple redefinitions or undefinitions). If the macro is + redefined/undefined on a per-compilation basis (ie. in the call to + :meth:`compile`), then that takes precedence. + + + .. method:: CCompiler.add_link_object(object) + + Add *object* to the list of object files (or analogues, such as explicitly named + library files or the output of "resource compilers") to be included in every + link driven by this compiler object. + + + .. method:: CCompiler.set_link_objects(objects) + + Set the list of object files (or analogues) to be included in every link to + *objects*. This does not affect any standard object files that the linker may + include by default (such as system libraries). + + The following methods implement methods for autodetection of compiler options, + providing some functionality similar to GNU :program:`autoconf`. + + + .. method:: CCompiler.detect_language(sources) + + Detect the language of a given file, or list of files. Uses the instance + attributes :attr:`~CCompiler.language_map` (a dictionary), and :attr:`~CCompiler.language_order` (a + list) to do the job. + + + .. method:: CCompiler.find_library_file(dirs, lib[, debug=0]) + + Search the specified list of directories for a static or shared library file + *lib* and return the full path to that file. If *debug* is true, look for a + debugging version (if that makes sense on the current platform). Return + ``None`` if *lib* wasn't found in any of the specified directories. + + + .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]) + + Return a boolean indicating whether *funcname* is supported on the current + platform. The optional arguments can be used to augment the compilation + environment by providing additional include files and paths and libraries and + paths. + + + .. method:: CCompiler.library_dir_option(dir) + + Return the compiler option to add *dir* to the list of directories searched for + libraries. + + + .. method:: CCompiler.library_option(lib) + + Return the compiler option to add *lib* to the list of libraries linked into the + shared library or executable. + + + .. method:: CCompiler.runtime_library_dir_option(dir) + + Return the compiler option to add *dir* to the list of directories searched for + runtime libraries. + + + .. method:: CCompiler.set_executables(**args) + + Define the executables (and options for them) that will be run to perform the + various stages of compilation. The exact set of executables that may be + specified here depends on the compiler class (via the 'executables' class + attribute), but most will have: + + +--------------+------------------------------------------+ + | attribute | description | + +==============+==========================================+ + | *compiler* | the C/C++ compiler | + +--------------+------------------------------------------+ + | *linker_so* | linker used to create shared objects and | + | | libraries | + +--------------+------------------------------------------+ + | *linker_exe* | linker used to create binary executables | + +--------------+------------------------------------------+ + | *archiver* | static library creator | + +--------------+------------------------------------------+ + + On platforms with a command-line (Unix, DOS/Windows), each of these is a string + that will be split into executable name and (optional) list of arguments. + (Splitting the string is done similarly to how Unix shells operate: words are + delimited by spaces, but quotes and backslashes can override this. See + :func:`distutils.util.split_quoted`.) + + The following methods invoke stages in the build process. + + + .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None]) + + Compile one or more source files. Generates object files (e.g. transforms a + :file:`.c` file to a :file:`.o` file.) + + *sources* must be a list of filenames, most likely C/C++ files, but in reality + anything that can be handled by a particular compiler and compiler class (eg. + :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of + object filenames, one per source filename in *sources*. Depending on the + implementation, not all source files will necessarily be compiled, but all + corresponding object filenames will be returned. + + If *output_dir* is given, object files will be put under it, while retaining + their original path component. That is, :file:`foo/bar.c` normally compiles to + :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then + it would compile to :file:`build/foo/bar.o`. + + *macros*, if given, must be a list of macro definitions. A macro definition is + either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines + a macro; if the value is ``None``, the macro is defined without an explicit + value. The 1-tuple case undefines a macro. Later + definitions/redefinitions/undefinitions take precedence. + + *include_dirs*, if given, must be a list of strings, the directories to add to + the default include file search path for this compilation only. + + *debug* is a boolean; if true, the compiler will be instructed to output debug + symbols in (or alongside) the object file(s). + + *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms + that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most + likely lists of strings: extra command-line arguments to prepend/append to the + compiler command line. On other platforms, consult the implementation class + documentation. In any event, they are intended as an escape hatch for those + occasions when the abstract compiler framework doesn't cut the mustard. + + *depends*, if given, is a list of filenames that all targets depend on. If a + source file is older than any file in depends, then the source file will be + recompiled. This supports dependency tracking, but only at a coarse + granularity. + + Raises :exc:`CompileError` on failure. + + + .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None]) + + Link a bunch of stuff together to create a static library file. The "bunch of + stuff" consists of the list of object files supplied as *objects*, the extra + object files supplied to :meth:`add_link_object` and/or + :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or + :meth:`set_libraries`, and the libraries supplied as *libraries* (if any). + + *output_libname* should be a library name, not a filename; the filename will be + inferred from the library name. *output_dir* is the directory where the library + file will be put. + + .. XXX defaults to what? + + *debug* is a boolean; if true, debugging information will be included in the + library (note that on most platforms, it is the compile step where this matters: + the *debug* flag is included here just for consistency). + + *target_lang* is the target language for which the given objects are being + compiled. This allows specific linkage time treatment of certain languages. + + Raises :exc:`LibError` on failure. + + + .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a bunch of stuff together to create an executable or shared library file. + + The "bunch of stuff" consists of the list of object files supplied as *objects*. + *output_filename* should be a filename. If *output_dir* is supplied, + *output_filename* is relative to it (i.e. *output_filename* can provide + directory components if needed). + + *libraries* is a list of libraries to link against. These are library names, + not filenames, since they're translated into filenames in a platform-specific + way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on + DOS/Windows). However, they can include a directory component, which means the + linker will look in that specific directory rather than searching all the normal + locations. + + *library_dirs*, if supplied, should be a list of directories to search for + libraries that were specified as bare library names (ie. no directory + component). These are on top of the system default and those supplied to + :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs* + is a list of directories that will be embedded into the shared library and used + to search for other shared libraries that \*it\* depends on at run-time. (This + may only be relevant on Unix.) + + *export_symbols* is a list of symbols that the shared library will export. + (This appears to be relevant only on Windows.) + + *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the + slight distinction that it actually matters on most platforms (as opposed to + :meth:`create_static_lib`, which includes a *debug* flag mostly for form's + sake). + + *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of + course that they supply command-line arguments for the particular linker being + used). + + *target_lang* is the target language for which the given objects are being + compiled. This allows specific linkage time treatment of certain languages. + + Raises :exc:`LinkError` on failure. + + + .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None]) + + Link an executable. *output_progname* is the name of the file executable, while + *objects* are a list of object filenames to link in. Other arguments are as for + the :meth:`link` method. + + + .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a shared library. *output_libname* is the name of the output library, + while *objects* is a list of object filenames to link in. Other arguments are + as for the :meth:`link` method. + + + .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a shared object. *output_filename* is the name of the shared object that + will be created, while *objects* is a list of object filenames to link in. + Other arguments are as for the :meth:`link` method. + + + .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]) + + Preprocess a single C/C++ source file, named in *source*. Output will be written + to file named *output_file*, or *stdout* if *output_file* not supplied. + *macros* is a list of macro definitions as for :meth:`compile`, which will + augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`. + *include_dirs* is a list of directory names that will be added to the default + list, in the same way as :meth:`add_include_dir`. + + Raises :exc:`PreprocessError` on failure. + + The following utility methods are defined by the :class:`CCompiler` class, for + use by the various concrete subclasses. + + + .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir='']) + + Returns the filename of the executable for the given *basename*. Typically for + non-Windows platforms this is the same as the basename, while Windows will get + a :file:`.exe` added. + + + .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir='']) + + Returns the filename for the given library name on the current platform. On Unix + a library with *lib_type* of ``'static'`` will typically be of the form + :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form + :file:`liblibname.so`. + + + .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir='']) + + Returns the name of the object files for the given source files. + *source_filenames* should be a list of filenames. + + + .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir='']) + + Returns the name of a shared object file for the given file name *basename*. + + + .. method:: CCompiler.execute(func, args[, msg=None, level=1]) + + Invokes :func:`distutils.util.execute`. This method invokes a Python function + *func* with the given arguments *args*, after logging and taking into account + the *dry_run* flag. + + + .. method:: CCompiler.spawn(cmd) + + Invokes :func:`distutils.spawn.spawn`. This invokes an external process to run + the given command. + + + .. method:: CCompiler.mkpath(name[, mode=511]) + + Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any + missing ancestor directories. + + + .. method:: CCompiler.move_file(src, dst) + + Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. + + + .. method:: CCompiler.announce(msg[, level=1]) + + Write a message using :func:`distutils.log.debug`. + + + .. method:: CCompiler.warn(msg) + + Write a warning message *msg* to standard error. + + + .. method:: CCompiler.debug_print(msg) + + If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to + standard output, otherwise do nothing. + +.. % \subsection{Compiler-specific modules} +.. % +.. % The following modules implement concrete subclasses of the abstract +.. % \class{CCompiler} class. They should not be instantiated directly, but should +.. % be created using \function{distutils.ccompiler.new_compiler()} factory +.. % function. + + +:mod:`distutils.unixccompiler` --- Unix C Compiler +================================================== + +.. module:: distutils.unixccompiler + :synopsis: UNIX C Compiler + + +This module provides the :class:`UnixCCompiler` class, a subclass of +:class:`CCompiler` that handles the typical Unix-style command-line C compiler: + +* macros defined with :option:`!-Dname[=value]` + +* macros undefined with :option:`!-Uname` + +* include search directories specified with :option:`!-Idir` + +* libraries specified with :option:`!-llib` + +* library search directories specified with :option:`!-Ldir` + +* compile handled by :program:`cc` (or similar) executable with :option:`!-c` + option: compiles :file:`.c` to :file:`.o` + +* link static library handled by :program:`ar` command (possibly with + :program:`ranlib`) + +* link shared library handled by :program:`cc` :option:`!-shared` + + +:mod:`distutils.msvccompiler` --- Microsoft Compiler +==================================================== + +.. module:: distutils.msvccompiler + :synopsis: Microsoft Compiler + +.. XXX: This is *waaaaay* out of date! + +This module provides :class:`MSVCCompiler`, an implementation of the abstract +:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension +modules need to be compiled with the same compiler that was used to compile +Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python +2.4 and 2.5, the compiler is Visual Studio .NET 2003. + +:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on +its own. To override this choice, the environment variables *DISTUTILS_USE_SDK* +and *MSSdk* must be both set. *MSSdk* indicates that the current environment has +been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables +had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates +that the distutils user has made an explicit choice to override the compiler +selection by :class:`MSVCCompiler`. + + +:mod:`distutils.bcppcompiler` --- Borland Compiler +================================================== + +.. module:: distutils.bcppcompiler + + +This module provides :class:`BorlandCCompiler`, a subclass of the abstract +:class:`CCompiler` class for the Borland C++ compiler. + + +:mod:`distutils.cygwinccompiler` --- Cygwin Compiler +==================================================== + +.. module:: distutils.cygwinccompiler + + +This module provides the :class:`CygwinCCompiler` class, a subclass of +:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to +Windows. It also contains the Mingw32CCompiler class which handles the mingw32 +port of GCC (same as cygwin in no-cygwin mode). + + +:mod:`distutils.archive_util` --- Archiving utilities +====================================================== + +.. module:: distutils.archive_util + :synopsis: Utility functions for creating archive files (tarballs, zip files, ...) + + +This module provides a few functions for creating archive files, such as +tarballs or zipfiles. + + +.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0]) + + Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of + the file to create, minus any format-specific extension; *format* is the + archive format: one of ``zip``, ``tar``, ``gztar``, ``bztar``, ``xztar``, or + ``ztar``. *root_dir* is a directory that will be the root directory of the + archive; ie. we typically ``chdir`` into *root_dir* before creating the + archive. *base_dir* is the directory where we start archiving from; ie. + *base_dir* will be the common prefix of all files and directories in the + archive. *root_dir* and *base_dir* both default to the current directory. + Returns the name of the archive file. + + .. versionchanged:: 3.5 + Added support for the ``xztar`` format. + + +.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) + + 'Create an (optional compressed) archive as a tar file from all files in and + under *base_dir*. *compress* must be ``'gzip'`` (the default), + ``'bzip2'``, ``'xz'``, ``'compress'``, or ``None``. For the ``'compress'`` + method the compression utility named by :program:`compress` must be on the + default program search path, so this is probably Unix-specific. The output + tar file will be named :file:`base_dir.tar`, possibly plus the appropriate + compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``). Return the + output filename. + + .. versionchanged:: 3.5 + Added support for the ``xz`` compression. + + +.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) + + Create a zip file from all files in and under *base_dir*. The output zip file + will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python + module (if available) or the InfoZIP :file:`zip` utility (if installed and + found on the default search path). If neither tool is available, raises + :exc:`DistutilsExecError`. Returns the name of the output zip file. + + +:mod:`distutils.dep_util` --- Dependency checking +================================================= + +.. module:: distutils.dep_util + :synopsis: Utility functions for simple dependency checking + + +This module provides functions for performing simple, timestamp-based +dependency of files and groups of files; also, functions based entirely on such +timestamp dependency analysis. + + +.. function:: newer(source, target) + + Return true if *source* exists and is more recently modified than *target*, or + if *source* exists and *target* doesn't. Return false if both exist and *target* + is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if + *source* does not exist. + + +.. function:: newer_pairwise(sources, targets) + + Walk two filename lists in parallel, testing if each source is newer than its + corresponding target. Return a pair of lists (*sources*, *targets*) where + source is newer than target, according to the semantics of :func:`newer`. + + .. % % equivalent to a listcomp... + + +.. function:: newer_group(sources, target[, missing='error']) + + Return true if *target* is out-of-date with respect to any file listed in + *sources*. In other words, if *target* exists and is newer than every file in + *sources*, return false; otherwise return true. *missing* controls what we do + when a source file is missing; the default (``'error'``) is to blow up with an + :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently + drop any missing source files; if it is ``'newer'``, any missing source files + make us assume that *target* is out-of-date (this is handy in "dry-run" mode: + it'll make you pretend to carry out commands that wouldn't work because inputs + are missing, but that doesn't matter because you're not actually going to run + the commands). + + +:mod:`distutils.dir_util` --- Directory tree operations +======================================================= + +.. module:: distutils.dir_util + :synopsis: Utility functions for operating on directories and directory trees + + +This module provides functions for operating on directories and trees of +directories. + + +.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0]) + + Create a directory and any missing ancestor directories. If the directory + already exists (or if *name* is the empty string, which means the current + directory, which of course exists), then do nothing. Raise + :exc:`DistutilsFileError` if unable to create some directory along the way (eg. + some sub-path exists, but is a file rather than a directory). If *verbose* is + true, print a one-line summary of each mkdir to stdout. Return the list of + directories actually created. + + +.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0]) + + Create all the empty directories under *base_dir* needed to put *files* there. + *base_dir* is just the name of a directory which doesn't necessarily exist + yet; *files* is a list of filenames to be interpreted relative to *base_dir*. + *base_dir* + the directory portion of every file in *files* will be created if + it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for + :func:`mkpath`. + + +.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0]) + + Copy an entire directory tree *src* to a new location *dst*. Both *src* and + *dst* must be directory names. If *src* is not a directory, raise + :exc:`DistutilsFileError`. If *dst* does not exist, it is created with + :func:`mkpath`. The end result of the copy is that every file in *src* is + copied to *dst*, and directories under *src* are recursively copied to *dst*. + Return the list of files that were copied or might have been copied, using their + output name. The return value is unaffected by *update* or *dry_run*: it is + simply the list of all files under *src*, with the names changed to be under + *dst*. + + *preserve_mode* and *preserve_times* are the same as for + :func:`distutils.file_util.copy_file`; note that they only apply to + regular files, not to + directories. If *preserve_symlinks* is true, symlinks will be copied as + symlinks (on platforms that support them!); otherwise (the default), the + destination of the symlink will be copied. *update* and *verbose* are the same + as for :func:`~distutils.file_util.copy_file`. + + Files in *src* that begin with :file:`.nfs` are skipped (more information on + these files is available in answer D2 of the `NFS FAQ page + <http://nfs.sourceforge.net/#section_d>`_). + + .. versionchanged:: 3.3.1 + NFS files are ignored. + +.. function:: remove_tree(directory[, verbose=0, dry_run=0]) + + Recursively remove *directory* and all files and directories underneath it. Any + errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is + true). + + +:mod:`distutils.file_util` --- Single file operations +===================================================== + +.. module:: distutils.file_util + :synopsis: Utility functions for operating on single files + + +This module contains some utility functions for operating on individual files. + + +.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0]) + + Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there + with the same name; otherwise, it must be a filename. (If the file exists, it + will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the + file's mode (type and permission bits, or whatever is analogous on the + current platform) is copied. If *preserve_times* is true (the default), the + last-modified and last-access times are copied as well. If *update* is true, + *src* will only be copied if *dst* does not exist, or if *dst* does exist but + is older than *src*. + + *link* allows you to make hard links (using :func:`os.link`) or symbolic links + (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or + ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link* + on systems that don't support it: :func:`copy_file` doesn't check if hard or + symbolic linking is available. It uses :func:`~distutils.file_util._copy_file_contents` to copy file + contents. + + Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the + output file, and *copied* is true if the file was copied (or would have been + copied, if *dry_run* true). + + .. % XXX if the destination file already exists, we clobber it if + .. % copying, but blow up if linking. Hmmm. And I don't know what + .. % macostools.copyfile() does. Should definitely be consistent, and + .. % should probably blow up if destination exists and we would be + .. % changing it (ie. it's not already a hard/soft link to src OR + .. % (not update) and (src newer than dst)). + + +.. function:: move_file(src, dst[, verbose, dry_run]) + + Move file *src* to *dst*. If *dst* is a directory, the file will be moved into + it with the same name; otherwise, *src* is just renamed to *dst*. Returns the + new full name of the file. + + .. warning:: + + Handles cross-device moves on Unix using :func:`copy_file`. What about + other systems? + + +.. function:: write_file(filename, contents) + + Create a file called *filename* and write *contents* (a sequence of strings + without line terminators) to it. + + +:mod:`distutils.util` --- Miscellaneous other utility functions +=============================================================== + +.. module:: distutils.util + :synopsis: Miscellaneous other utility functions + + +This module contains other assorted bits and pieces that don't fit into any +other utility module. + + +.. function:: get_platform() + + Return a string that identifies the current platform. This is used mainly to + distinguish platform-specific build directories and platform-specific built + distributions. Typically includes the OS name and version and the + architecture (as supplied by 'os.uname()'), although the exact information + included depends on the OS; e.g., on Linux, the kernel version isn't + particularly important. + + Examples of returned values: + + * ``linux-i586`` + * ``linux-alpha`` + * ``solaris-2.6-sun4u`` + + For non-POSIX platforms, currently just returns ``sys.platform``. + + For Mac OS X systems the OS version reflects the minimal version on which + binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` + during the build of Python), not the OS version of the current system. + + For universal binary builds on Mac OS X the architecture value reflects + the universal binary status instead of the architecture of the current + processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and + for 4-way universal binaries the architecture is ``universal``. Starting + from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for + a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for + a universal build with the i386 and x86_64 architectures + + Examples of returned values on Mac OS X: + + * ``macosx-10.3-ppc`` + + * ``macosx-10.3-fat`` + + * ``macosx-10.5-universal`` + + * ``macosx-10.6-intel`` + + For AIX, Python 3.9 and later return a string starting with "aix", followed + by additional fields (separated by ``'-'``) that represent the combined + values of AIX Version, Release and Technology Level (first field), Build Date + (second field), and bit-size (third field). Python 3.8 and earlier returned + only a single additional field with the AIX Version and Release. + + Examples of returned values on AIX: + + * ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000 + + * ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731 + + * ``aix-7.2`` # Legacy form reported in Python 3.8 and earlier + + .. versionchanged:: 3.9 + The AIX platform string format now also includes the technology level, + build date, and ABI bit-size. + + +.. function:: convert_path(pathname) + + Return 'pathname' as a name that will work on the native filesystem, i.e. split + it on '/' and put it back together again using the current directory separator. + Needed because filenames in the setup script are always supplied in Unix style, + and have to be converted to the local convention before we can actually use them + in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if + *pathname* either starts or ends with a slash. + + +.. function:: change_root(new_root, pathname) + + Return *pathname* with *new_root* prepended. If *pathname* is relative, this is + equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making + *pathname* relative and then joining the two, which is tricky on DOS/Windows. + + +.. function:: check_environ() + + Ensure that 'os.environ' has all the environment variables we guarantee that + users can use in config files, command-line options, etc. Currently this + includes: + + * :envvar:`HOME` - user's home directory (Unix only) + * :envvar:`PLAT` - description of the current platform, including hardware and + OS (see :func:`get_platform`) + + +.. function:: subst_vars(s, local_vars) + + Perform shell/Perl-style variable substitution on *s*. Every occurrence of + ``$`` followed by a name is considered a variable, and variable is substituted + by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's + not in *local_vars*. *os.environ* is first checked/augmented to guarantee that + it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError` + for any variables not found in either *local_vars* or ``os.environ``. + + Note that this is not a fully-fledged string interpolation function. A valid + ``$variable`` can consist only of upper and lower case letters, numbers and an + underscore. No { } or ( ) style quoting is available. + + +.. function:: split_quoted(s) + + Split a string up according to Unix shell-like rules for quotes and backslashes. + In short: words are delimited by spaces, as long as those spaces are not escaped + by a backslash, or inside a quoted string. Single and double quotes are + equivalent, and the quote characters can be backslash-escaped. The backslash is + stripped from any two-character escape sequence, leaving only the escaped + character. The quote characters are stripped from any quoted string. Returns a + list of words. + + .. % Should probably be moved into the standard library. + + +.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0]) + + Perform some action that affects the outside world (for instance, writing to the + filesystem). Such actions are special because they are disabled by the + *dry_run* flag. This method takes care of all that bureaucracy for you; all + you have to do is supply the function to call and an argument tuple for it (to + embody the "external action" being performed), and an optional message to print. + + +.. function:: strtobool(val) + + Convert a string representation of truth to true (1) or false (0). + + True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values + are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises + :exc:`ValueError` if *val* is anything else. + + +.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) + + Byte-compile a collection of Python source files to :file:`.pyc` files in a + :file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`). + *py_files* is a list of files to compile; any files that don't end in + :file:`.py` are silently skipped. *optimize* must be one of the following: + + * ``0`` - don't optimize + * ``1`` - normal optimization (like ``python -O``) + * ``2`` - extra optimization (like ``python -OO``) + + If *force* is true, all files are recompiled regardless of timestamps. + + The source filename encoded in each :term:`bytecode` file defaults to the filenames + listed in *py_files*; you can modify these with *prefix* and *basedir*. + *prefix* is a string that will be stripped off of each source filename, and + *base_dir* is a directory name that will be prepended (after *prefix* is + stripped). You can supply either or both (or neither) of *prefix* and + *base_dir*, as you wish. + + If *dry_run* is true, doesn't actually do anything that would affect the + filesystem. + + Byte-compilation is either done directly in this interpreter process with the + standard :mod:`py_compile` module, or indirectly by writing a temporary script + and executing it. Normally, you should let :func:`byte_compile` figure out to + use direct compilation or not (see the source for details). The *direct* flag + is used by the script generated in indirect mode; unless you know what you're + doing, leave it set to ``None``. + + .. versionchanged:: 3.2.3 + Create ``.pyc`` files with an :func:`import magic tag + <imp.get_tag>` in their name, in a :file:`__pycache__` subdirectory + instead of files without tag in the current directory. + + .. versionchanged:: 3.5 + Create ``.pyc`` files according to :pep:`488`. + + +.. function:: rfc822_escape(header) + + Return a version of *header* escaped for inclusion in an :rfc:`822` header, by + ensuring there are 8 spaces space after each newline. Note that it does no other + modification of the string. + + .. % this _can_ be replaced + +.. % \subsection{Distutils objects} + + +:mod:`distutils.dist` --- The Distribution class +================================================ + +.. module:: distutils.dist + :synopsis: Provides the Distribution class, which represents the module distribution being + built/installed/distributed + + +This module provides the :class:`~distutils.core.Distribution` class, which +represents the module distribution being built/installed/distributed. + + +:mod:`distutils.extension` --- The Extension class +================================================== + +.. module:: distutils.extension + :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup + scripts + + +This module provides the :class:`~distutils.extension.Extension` class, +used to describe C/C++ extension modules in setup scripts. + +.. % \subsection{Ungrouped modules} +.. % The following haven't been moved into a more appropriate section yet. + + +:mod:`distutils.debug` --- Distutils debug mode +=============================================== + +.. module:: distutils.debug + :synopsis: Provides the debug flag for distutils + + +This module provides the DEBUG flag. + + +:mod:`distutils.errors` --- Distutils exceptions +================================================ + +.. module:: distutils.errors + :synopsis: Provides standard distutils exceptions + + +Provides exceptions used by the Distutils modules. Note that Distutils modules +may raise standard exceptions; in particular, SystemExit is usually raised for +errors that are obviously the end-user's fault (eg. bad command-line arguments). + +This module is safe to use in ``from ... import *`` mode; it only exports +symbols whose names start with ``Distutils`` and end with ``Error``. + + +:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module +=========================================================================== + +.. module:: distutils.fancy_getopt + :synopsis: Additional getopt functionality + + +This module provides a wrapper around the standard :mod:`getopt` module that +provides the following additional features: + +* short and long options are tied together + +* options have help strings, so :func:`fancy_getopt` could potentially create a + complete usage summary + +* options set attributes of a passed-in object + +* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is + the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the + command line sets *verbose* to false. + +.. function:: fancy_getopt(options, negative_opt, object, args) + + Wrapper function. *options* is a list of ``(long_option, short_option, + help_string)`` 3-tuples as described in the constructor for + :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names + to option names, both the key and value should be in the *options* list. + *object* is an object which will be used to store values (see the :meth:`~FancyGetopt.getopt` + method of the :class:`FancyGetopt` class). *args* is the argument list. Will use + ``sys.argv[1:]`` if you pass ``None`` as *args*. + + +.. function:: wrap_text(text, width) + + Wraps *text* to less than *width* wide. + + +.. class:: FancyGetopt([option_table=None]) + + The option_table is a list of 3-tuples: ``(long_option, short_option, + help_string)`` + + If an option takes an argument, its *long_option* should have ``'='`` appended; + *short_option* should just be a single character, no ``':'`` in any case. + *short_option* should be ``None`` if a *long_option* doesn't have a + corresponding *short_option*. All option tuples must have long options. + +The :class:`FancyGetopt` class provides the following methods: + + +.. method:: FancyGetopt.getopt([args=None, object=None]) + + Parse command-line options in args. Store as attributes on *object*. + + If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is + ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores + option values there, and returns a tuple ``(args, object)``. If *object* is + supplied, it is modified in place and :func:`getopt` just returns *args*; in + both cases, the returned *args* is a modified copy of the passed-in *args* list, + which is left untouched. + + .. % and args returned are? + + +.. method:: FancyGetopt.get_option_order() + + Returns the list of ``(option, value)`` tuples processed by the previous run of + :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called + yet. + + +.. method:: FancyGetopt.generate_help([header=None]) + + Generate help text (a list of strings, one per suggested line of output) from + the option table for this :class:`FancyGetopt` object. + + If supplied, prints the supplied *header* at the top of the help. + + +:mod:`distutils.filelist` --- The FileList class +================================================ + +.. module:: distutils.filelist + :synopsis: The FileList class, used for poking about the file system and + building lists of files. + + +This module provides the :class:`FileList` class, used for poking about the +filesystem and building lists of files. + + +:mod:`distutils.log` --- Simple :pep:`282`-style logging +======================================================== + +.. module:: distutils.log + :synopsis: A simple logging mechanism, :pep:`282`-style + + +:mod:`distutils.spawn` --- Spawn a sub-process +============================================== + +.. module:: distutils.spawn + :synopsis: Provides the spawn() function + + +This module provides the :func:`~distutils.spawn.spawn` function, a +front-end to various platform-specific functions for launching another +program in a sub-process. +Also provides :func:`~distutils.spawn.find_executable` to search the path for a given executable +name. + + +:mod:`distutils.sysconfig` --- System configuration information +=============================================================== + +.. module:: distutils.sysconfig + :synopsis: Low-level access to configuration information of the Python interpreter. +.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> +.. moduleauthor:: Greg Ward <gward@python.net> +.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> + + +The :mod:`distutils.sysconfig` module provides access to Python's low-level +configuration information. The specific configuration variables available +depend heavily on the platform and configuration. The specific variables depend +on the build process for the specific version of Python being run; the variables +are those found in the :file:`Makefile` and configuration header that are +installed with Python on Unix systems. The configuration header is called +:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` +for earlier versions of Python. + +Some additional functions are provided which perform some useful manipulations +for other parts of the :mod:`distutils` package. + + +.. data:: PREFIX + + The result of ``os.path.normpath(sys.prefix)``. + + +.. data:: EXEC_PREFIX + + The result of ``os.path.normpath(sys.exec_prefix)``. + + +.. function:: get_config_var(name) + + Return the value of a single variable. This is equivalent to + ``get_config_vars().get(name)``. + + +.. function:: get_config_vars(...) + + Return a set of variable definitions. If there are no arguments, this returns a + dictionary mapping names of configuration variables to values. If arguments are + provided, they should be strings, and the return value will be a sequence giving + the associated values. If a given name does not have a corresponding value, + ``None`` will be included for that variable. + + +.. function:: get_config_h_filename() + + Return the full path name of the configuration header. For Unix, this will be + the header generated by the :program:`configure` script; for other platforms the + header will have been supplied directly by the Python source distribution. The + file is a platform-specific text file. + + +.. function:: get_makefile_filename() + + Return the full path name of the :file:`Makefile` used to build Python. For + Unix, this will be a file generated by the :program:`configure` script; the + meaning for other platforms will vary. The file is a platform-specific text + file, if it exists. This function is only useful on POSIX platforms. + + +.. function:: get_python_inc([plat_specific[, prefix]]) + + Return the directory for either the general or platform-dependent C include + files. If *plat_specific* is true, the platform-dependent include directory is + returned; if false or omitted, the platform-independent directory is returned. + If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. + + +.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) + + Return the directory for either the general or platform-dependent library + installation. If *plat_specific* is true, the platform-dependent include + directory is returned; if false or omitted, the platform-independent directory + is returned. If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. If *standard_lib* is true, the directory for the + standard library is returned rather than the directory for the installation of + third-party extensions. + +The following function is only intended for use within the :mod:`distutils` +package. + + +.. function:: customize_compiler(compiler) + + Do any platform-specific customization of a + :class:`distutils.ccompiler.CCompiler` instance. + + This function is only needed on Unix at this time, but should be called + consistently to support forward-compatibility. It inserts the information that + varies across Unix flavors and is stored in Python's :file:`Makefile`. This + information includes the selected compiler, compiler and linker options, and the + extension used by the linker for shared objects. + +This function is even more special-purpose, and should only be used from +Python's own build procedures. + + +.. function:: set_python_build() + + Inform the :mod:`distutils.sysconfig` module that it is being used as part of + the build process for Python. This changes a lot of relative locations for + files, allowing them to be located in the build area rather than in an installed + Python. + + +:mod:`distutils.text_file` --- The TextFile class +================================================= + +.. module:: distutils.text_file + :synopsis: Provides the TextFile class, a simple interface to text files + + +This module provides the :class:`TextFile` class, which gives an interface to +text files that (optionally) takes care of stripping comments, ignoring blank +lines, and joining lines with backslashes. + + +.. class:: TextFile([filename=None, file=None, **options]) + + This class provides a file-like object that takes care of all the things you + commonly want to do when processing a text file that has some line-by-line + syntax: strip comments (as long as ``#`` is your comment character), skip blank + lines, join adjacent lines by escaping the newline (ie. backslash at end of + line), strip leading and/or trailing whitespace. All of these are optional and + independently controllable. + + The class provides a :meth:`warn` method so you can generate warning messages + that report physical line number, even if the logical line in question spans + multiple physical lines. Also provides :meth:`unreadline` for implementing + line-at-a-time lookahead. + + :class:`TextFile` instances are create with either *filename*, *file*, or both. + :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a + string, and *file* a file object (or something that provides :meth:`readline` + and :meth:`close` methods). It is recommended that you supply at least + *filename*, so that :class:`TextFile` can include it in warning messages. If + *file* is not supplied, :class:`TextFile` creates its own using the + :func:`open` built-in function. + + The options are all boolean, and affect the values returned by :meth:`readline` + + .. tabularcolumns:: |l|L|l| + + +------------------+--------------------------------+---------+ + | option name | description | default | + +==================+================================+=========+ + | *strip_comments* | strip from ``'#'`` to | true | + | | end-of-line, as well as any | | + | | whitespace leading up to the | | + | | ``'#'``\ ---unless it is | | + | | escaped by a backslash | | + +------------------+--------------------------------+---------+ + | *lstrip_ws* | strip leading whitespace from | false | + | | each line before returning it | | + +------------------+--------------------------------+---------+ + | *rstrip_ws* | strip trailing whitespace | true | + | | (including line terminator!) | | + | | from each line before | | + | | returning it. | | + +------------------+--------------------------------+---------+ + | *skip_blanks* | skip lines that are empty | true | + | | \*after\* stripping comments | | + | | and whitespace. (If both | | + | | lstrip_ws and rstrip_ws are | | + | | false, then some lines may | | + | | consist of solely whitespace: | | + | | these will \*not\* be skipped, | | + | | even if *skip_blanks* is | | + | | true.) | | + +------------------+--------------------------------+---------+ + | *join_lines* | if a backslash is the last | false | + | | non-newline character on a | | + | | line after stripping comments | | + | | and whitespace, join the | | + | | following line to it to form | | + | | one logical line; if N | | + | | consecutive lines end with a | | + | | backslash, then N+1 physical | | + | | lines will be joined to form | | + | | one logical line. | | + +------------------+--------------------------------+---------+ + | *collapse_join* | strip leading whitespace from | false | + | | lines that are joined to their | | + | | predecessor; only matters if | | + | | ``(join_lines and not | | + | | lstrip_ws)`` | | + +------------------+--------------------------------+---------+ + + Note that since *rstrip_ws* can strip the trailing newline, the semantics of + :meth:`readline` must differ from those of the built-in file object's + :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for + end-of-file: an empty string might just be a blank line (or an all-whitespace + line), if *rstrip_ws* is true but *skip_blanks* is not. + + + .. method:: TextFile.open(filename) + + Open a new file *filename*. This overrides any *file* or *filename* + constructor arguments. + + + .. method:: TextFile.close() + + Close the current file and forget everything we know about it (including the + filename and the current line number). + + + .. method:: TextFile.warn(msg[,line=None]) + + Print (to stderr) a warning message tied to the current logical line in the + current file. If the current logical line in the file spans multiple physical + lines, the warning refers to the whole range, such as ``"lines 3-5"``. If + *line* is supplied, it overrides the current line number; it may be a list or + tuple to indicate a range of physical lines, or an integer for a single + physical line. + + + .. method:: TextFile.readline() + + Read and return a single logical line from the current file (or from an internal + buffer if lines have previously been "unread" with :meth:`unreadline`). If the + *join_lines* option is true, this may involve reading multiple physical lines + concatenated into a single string. Updates the current line number, so calling + :meth:`warn` after :meth:`readline` emits a warning about the physical line(s) + just read. Returns ``None`` on end-of-file, since the empty string can occur + if *rstrip_ws* is true but *strip_blanks* is not. + + + .. method:: TextFile.readlines() + + Read and return the list of all logical lines remaining in the current file. + This updates the current line number to the last line of the file. + + + .. method:: TextFile.unreadline(line) + + Push *line* (a string) onto an internal buffer that will be checked by future + :meth:`readline` calls. Handy for implementing a parser with line-at-a-time + lookahead. Note that lines that are "unread" with :meth:`unreadline` are not + subsequently re-cleansed (whitespace stripped, or whatever) when read with + :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call + to :meth:`readline`, the lines will be returned most in most recent first order. + + +:mod:`distutils.version` --- Version number classes +=================================================== + +.. module:: distutils.version + :synopsis: Implements classes that represent module version numbers. + + +.. % todo +.. % \section{Distutils Commands} +.. % +.. % This part of Distutils implements the various Distutils commands, such +.. % as \code{build}, \code{install} \&c. Each command is implemented as a +.. % separate module, with the command name as the name of the module. + + +:mod:`distutils.cmd` --- Abstract base class for Distutils commands +=================================================================== + +.. module:: distutils.cmd + :synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class + is subclassed by the modules in the distutils.command subpackage. + + +This module supplies the abstract base class :class:`Command`. + + +.. class:: Command(dist) + + Abstract base class for defining command classes, the "worker bees" of the + Distutils. A useful analogy for command classes is to think of them as + subroutines with local variables called *options*. The options are declared + in :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command + class. The distinction between the two is necessary because option values + might come from the outside world (command line, config file, ...), and any + options dependent on other options must be computed after these outside + influences have been processed --- hence :meth:`finalize_options`. The body + of the subroutine, where it does all its work based on the values of its + options, is the :meth:`run` method, which must also be implemented by every + command class. + + The class constructor takes a single argument *dist*, a + :class:`~distutils.core.Distribution` instance. + + +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class ``peel_banana``, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + +.. method:: Command.initialize_options() + + Set default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + + +.. attribute:: Command.sub_commands + + *sub_commands* formalizes the notion of a "family" of commands, + e.g. ``install`` as the parent with sub-commands ``install_lib``, + ``install_headers``, etc. The parent of a family of commands defines + *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, + predicate)``, with *command_name* a string and *predicate* a function, a + string or ``None``. *predicate* is a method of the parent command that + determines whether the corresponding command is applicable in the current + situation. (E.g. ``install_headers`` is only applicable if we have any C + header files to install.) If *predicate* is ``None``, that command is always + applicable. + + *sub_commands* is usually defined at the *end* of a class, because + predicates can be methods of the class, so they must already have been + defined. The canonical example is the :command:`install` command. + + +:mod:`distutils.command` --- Individual Distutils commands +========================================================== + +.. module:: distutils.command + :synopsis: Contains one module for each standard Distutils command. + + +.. % \subsubsection{Individual Distutils commands} +.. % todo + + +:mod:`distutils.command.bdist` --- Build a binary installer +=========================================================== + +.. module:: distutils.command.bdist + :synopsis: Build a binary installer for a package + + +.. % todo + + +:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers +============================================================================= + +.. module:: distutils.command.bdist_packager + :synopsis: Abstract base class for packagers + + +.. % todo + + +:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer +================================================================ + +.. module:: distutils.command.bdist_dumb + :synopsis: Build a "dumb" installer - a simple archive of files + + +:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM +=========================================================================================== + +.. module:: distutils.command.bdist_rpm + :synopsis: Build a binary distribution as a Redhat RPM and SRPM + + +.. % todo + + +:mod:`distutils.command.sdist` --- Build a source distribution +============================================================== + +.. module:: distutils.command.sdist + :synopsis: Build a source distribution + + +.. % todo + + +:mod:`distutils.command.build` --- Build all files of a package +=============================================================== + +.. module:: distutils.command.build + :synopsis: Build all files of a package + + +.. % todo + + +:mod:`distutils.command.build_clib` --- Build any C libraries in a package +========================================================================== + +.. module:: distutils.command.build_clib + :synopsis: Build any C libraries in a package + + +.. % todo + + +:mod:`distutils.command.build_ext` --- Build any extensions in a package +======================================================================== + +.. module:: distutils.command.build_ext + :synopsis: Build any extensions in a package + + +.. % todo + + +:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package +=========================================================================== + +.. module:: distutils.command.build_py + :synopsis: Build the .py/.pyc files of a package + + +.. class:: build_py + + +:mod:`distutils.command.build_scripts` --- Build the scripts of a package +========================================================================= + +.. module:: distutils.command.build_scripts + :synopsis: Build the scripts of a package + + +.. % todo + + +:mod:`distutils.command.clean` --- Clean a package build area +============================================================= + +.. module:: distutils.command.clean + :synopsis: Clean a package build area + +This command removes the temporary files created by :command:`build` +and its subcommands, like intermediary compiled object files. With +the ``--all`` option, the complete build directory will be removed. + +Extension modules built :ref:`in place <distutils-build-ext-inplace>` +will not be cleaned, as they are not in the build directory. + + +:mod:`distutils.command.config` --- Perform package configuration +================================================================= + +.. module:: distutils.command.config + :synopsis: Perform package configuration + + +.. % todo + + +:mod:`distutils.command.install` --- Install a package +====================================================== + +.. module:: distutils.command.install + :synopsis: Install a package + + +.. % todo + + +:mod:`distutils.command.install_data` --- Install data files from a package +=========================================================================== + +.. module:: distutils.command.install_data + :synopsis: Install data files from a package + + +.. % todo + + +:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package +====================================================================================== + +.. module:: distutils.command.install_headers + :synopsis: Install C/C++ header files from a package + + +.. % todo + + +:mod:`distutils.command.install_lib` --- Install library files from a package +============================================================================= + +.. module:: distutils.command.install_lib + :synopsis: Install library files from a package + + +.. % todo + + +:mod:`distutils.command.install_scripts` --- Install script files from a package +================================================================================ + +.. module:: distutils.command.install_scripts + :synopsis: Install script files from a package + + +.. % todo + + +:mod:`distutils.command.register` --- Register a module with the Python Package Index +===================================================================================== + +.. module:: distutils.command.register + :synopsis: Register a module with the Python Package Index + + +The ``register`` command registers the package with the Python Package Index. +This is described in more detail in :pep:`301`. + +.. % todo + + +:mod:`distutils.command.check` --- Check the meta-data of a package +=================================================================== + +.. module:: distutils.command.check + :synopsis: Check the meta-data of a package + + +The ``check`` command performs some tests on the meta-data of a package. +For example, it verifies that all required meta-data are provided as +the arguments passed to the :func:`~distutils.core.setup` function. + +.. % todo diff --git a/docs/deprecated/distutils/builtdist.rst b/docs/deprecated/distutils/builtdist.rst new file mode 100644 index 00000000..052a5850 --- /dev/null +++ b/docs/deprecated/distutils/builtdist.rst @@ -0,0 +1,388 @@ +.. _built-dist: + +**************************** +Creating Built Distributions +**************************** + +.. include:: ./_setuptools_disclaimer.rst + +A "built distribution" is what you're probably used to thinking of either as a +"binary package" or an "installer" (depending on your background). It's not +necessarily binary, though, because it might contain only Python source code +and/or byte-code; and we don't call it a package, because that word is already +spoken for in Python. (And "installer" is a term specific to the world of +mainstream desktop systems.) + +A built distribution is how you make life as easy as possible for installers of +your module distribution: for users of RPM-based Linux systems, it's a binary +RPM; for Windows users, it's an executable installer; for Debian-based Linux +users, it's a Debian package; and so forth. Obviously, no one person will be +able to create built distributions for every platform under the sun, so the +Distutils are designed to enable module developers to concentrate on their +specialty---writing code and creating source distributions---while an +intermediary species called *packagers* springs up to turn source distributions +into built distributions for as many platforms as there are packagers. + +Of course, the module developer could be their own packager; or the packager could +be a volunteer "out there" somewhere who has access to a platform which the +original developer does not; or it could be software periodically grabbing new +source distributions and turning them into built distributions for as many +platforms as the software has access to. Regardless of who they are, a packager +uses the setup script and the :command:`bdist` command family to generate built +distributions. + +As a simple example, if I run the following command in the Distutils source +tree:: + + python setup.py bdist + +then the Distutils builds my module distribution (the Distutils itself in this +case), does a "fake" installation (also in the :file:`build` directory), and +creates the default type of built distribution for my platform. The default +format for built distributions is a "dumb" tar file on Unix, and a simple +executable installer on Windows. (That tar file is considered "dumb" because it +has to be unpacked in a specific location to work.) + +Thus, the above command on a Unix system creates +:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place +installs the Distutils just as though you had downloaded the source distribution +and run ``python setup.py install``. (The "right place" is either the root of +the filesystem or Python's :file:`{prefix}` directory, depending on the options +given to the :command:`bdist_dumb` command; the default is to make dumb +distributions relative to :file:`{prefix}`.) + +Obviously, for pure Python distributions, this isn't any simpler than just +running ``python setup.py install``\ ---but for non-pure distributions, which +include extensions that would need to be compiled, it can mean the difference +between someone being able to use your extensions or not. And creating "smart" +built distributions, such as an RPM package or an executable installer for +Windows, is far more convenient for users even if your distribution doesn't +include any extensions. + +The :command:`bdist` command has a :option:`!--formats` option, similar to the +:command:`sdist` command, which you can use to select the types of built +distribution to generate: for example, :: + + python setup.py bdist --format=zip + +would, when run on a Unix system, create +:file:`Distutils-1.0.{plat}.zip`\ ---again, this archive would be unpacked +from the root directory to install the Distutils. + +The available formats for built distributions are: + ++-------------+------------------------------+---------+ +| Format | Description | Notes | ++=============+==============================+=========+ +| ``gztar`` | gzipped tar file | \(1) | +| | (:file:`.tar.gz`) | | ++-------------+------------------------------+---------+ +| ``bztar`` | bzipped tar file | | +| | (:file:`.tar.bz2`) | | ++-------------+------------------------------+---------+ +| ``xztar`` | xzipped tar file | | +| | (:file:`.tar.xz`) | | ++-------------+------------------------------+---------+ +| ``ztar`` | compressed tar file | \(3) | +| | (:file:`.tar.Z`) | | ++-------------+------------------------------+---------+ +| ``tar`` | tar file (:file:`.tar`) | | ++-------------+------------------------------+---------+ +| ``zip`` | zip file (:file:`.zip`) | (2),(4) | ++-------------+------------------------------+---------+ +| ``rpm`` | RPM | \(5) | ++-------------+------------------------------+---------+ +| ``pkgtool`` | Solaris :program:`pkgtool` | | ++-------------+------------------------------+---------+ +| ``sdux`` | HP-UX :program:`swinstall` | | ++-------------+------------------------------+---------+ + +.. versionchanged:: 3.5 + Added support for the ``xztar`` format. + + +Notes: + +(1) + default on Unix + +(2) + default on Windows + +(3) + requires external :program:`compress` utility. + +(4) + requires either external :program:`zip` utility or :mod:`zipfile` module (part + of the standard Python library since Python 1.6) + +(5) + requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm + --version`` to find out which version you have) + +You don't have to use the :command:`bdist` command with the :option:`!--formats` +option; you can also use the command that directly implements the format you're +interested in. Some of these :command:`bdist` "sub-commands" actually generate +several similar formats; for instance, the :command:`bdist_dumb` command +generates all the "dumb" archive formats (``tar``, ``gztar``, ``bztar``, +``xztar``, ``ztar``, and ``zip``), and :command:`bdist_rpm` generates both +binary and source RPMs. The :command:`bdist` sub-commands, and the formats +generated by each, are: + ++--------------------------+-------------------------------------+ +| Command | Formats | ++==========================+=====================================+ +| :command:`bdist_dumb` | tar, gztar, bztar, xztar, ztar, zip | ++--------------------------+-------------------------------------+ +| :command:`bdist_rpm` | rpm, srpm | ++--------------------------+-------------------------------------+ + +The following sections give details on the individual :command:`bdist_\*` +commands. + + +.. .. _creating-dumb: + +.. Creating dumb built distributions +.. ================================= + +.. XXX Need to document absolute vs. prefix-relative packages here, but first + I have to implement it! + + +.. _creating-rpms: + +Creating RPM packages +===================== + +The RPM format is used by many popular Linux distributions, including Red Hat, +SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux +distributions) is your usual environment, creating RPM packages for other users +of that same distribution is trivial. Depending on the complexity of your module +distribution and differences between Linux distributions, you may also be able +to create RPMs that work on different RPM-based distributions. + +The usual way to create an RPM of your module distribution is to run the +:command:`bdist_rpm` command:: + + python setup.py bdist_rpm + +or the :command:`bdist` command with the :option:`!--format` option:: + + python setup.py bdist --formats=rpm + +The former allows you to specify RPM-specific options; the latter allows you to +easily specify multiple formats in one run. If you need to do both, you can +explicitly specify multiple :command:`bdist_\*` commands and their options:: + + python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \ + bdist_dumb --dumb-option=foo + +Creating RPM packages is driven by a :file:`.spec` file, much as using the +Distutils is driven by the setup script. To make your life easier, the +:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the +information you supply in the setup script, on the command line, and in any +Distutils configuration files. Various options and sections in the +:file:`.spec` file are derived from options in the setup script as follows: + ++------------------------------------------+----------------------------------------------+ +| RPM :file:`.spec` file option or section | Distutils setup script option | ++==========================================+==============================================+ +| Name | ``name`` | ++------------------------------------------+----------------------------------------------+ +| Summary (in preamble) | ``description`` | ++------------------------------------------+----------------------------------------------+ +| Version | ``version`` | ++------------------------------------------+----------------------------------------------+ +| Vendor | ``author`` and ``author_email``, | +| | or --- & ``maintainer`` and | +| | ``maintainer_email`` | ++------------------------------------------+----------------------------------------------+ +| Copyright | ``license`` | ++------------------------------------------+----------------------------------------------+ +| Url | ``url`` | ++------------------------------------------+----------------------------------------------+ +| %description (section) | ``long_description`` | ++------------------------------------------+----------------------------------------------+ + +Additionally, there are many options in :file:`.spec` files that don't have +corresponding options in the setup script. Most of these are handled through +options to the :command:`bdist_rpm` command as follows: + ++-------------------------------+-----------------------------+-------------------------+ +| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value | +| or section | | | ++===============================+=============================+=========================+ +| Release | ``release`` | "1" | ++-------------------------------+-----------------------------+-------------------------+ +| Group | ``group`` | "Development/Libraries" | ++-------------------------------+-----------------------------+-------------------------+ +| Vendor | ``vendor`` | (see above) | ++-------------------------------+-----------------------------+-------------------------+ +| Packager | ``packager`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Provides | ``provides`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Requires | ``requires`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Conflicts | ``conflicts`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Obsoletes | ``obsoletes`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Distribution | ``distribution_name`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| BuildRequires | ``build_requires`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Icon | ``icon`` | (none) | ++-------------------------------+-----------------------------+-------------------------+ + +Obviously, supplying even a few of these options on the command-line would be +tedious and error-prone, so it's usually best to put them in the setup +configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If +you distribute or package many Python module distributions, you might want to +put options that apply to all of them in your personal Distutils configuration +file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable +this file, you can pass the :option:`!--no-user-cfg` option to :file:`setup.py`. + +There are three steps to building a binary RPM package, all of which are +handled automatically by the Distutils: + +#. create a :file:`.spec` file, which describes the package (analogous to the + Distutils setup script; in fact, much of the information in the setup script + winds up in the :file:`.spec` file) + +#. create the source RPM + +#. create the "binary" RPM (which may or may not contain binary code, depending + on whether your module distribution contains Python extensions) + +Normally, RPM bundles the last two steps together; when you use the Distutils, +all three steps are typically bundled together. + +If you wish, you can separate these three steps. You can use the +:option:`!--spec-only` option to make :command:`bdist_rpm` just create the +:file:`.spec` file and exit; in this case, the :file:`.spec` file will be +written to the "distribution directory"---normally :file:`dist/`, but +customizable with the :option:`!--dist-dir` option. (Normally, the :file:`.spec` +file winds up deep in the "build tree," in a temporary directory created by +:command:`bdist_rpm`.) + +.. % \XXX{this isn't implemented yet---is it needed?!} +.. % You can also specify a custom \file{.spec} file with the +.. % \longprogramopt{spec-file} option; used in conjunction with +.. % \longprogramopt{spec-only}, this gives you an opportunity to customize +.. % the \file{.spec} file manually: +.. % +.. % \ begin{verbatim} +.. % > python setup.py bdist_rpm --spec-only +.. % # ...edit dist/FooBar-1.0.spec +.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec +.. % \ end{verbatim} +.. % +.. % (Although a better way to do this is probably to override the standard +.. % \command{bdist\_rpm} command with one that writes whatever else you want +.. % to the \file{.spec} file.) + +.. _cross-compile-windows: + +Cross-compiling on Windows +========================== + +Starting with Python 2.6, distutils is capable of cross-compiling between +Windows platforms. In practice, this means that with the correct tools +installed, you can use a 32bit version of Windows to create 64bit extensions +and vice-versa. + +To build for an alternate platform, specify the :option:`!--plat-name` option +to the build command. Valid values are currently 'win32', and 'win-amd64'. +For example, on a 32bit version of Windows, you could execute:: + + python setup.py build --plat-name=win-amd64 + +to build a 64bit version of your extension. + +To cross-compile, you must download the Python source code and cross-compile +Python itself for the platform you are targeting - it is not possible from a +binary installation of Python (as the .lib etc file for other platforms are +not included.) In practice, this means the user of a 32 bit operating +system will need to use Visual Studio 2008 to open the +:file:`PCbuild/PCbuild.sln` solution in the Python source tree and build the +"x64" configuration of the 'pythoncore' project before cross-compiling +extensions is possible. + +Note that by default, Visual Studio 2008 does not install 64bit compilers or +tools. You may need to reexecute the Visual Studio setup process and select +these tools (using Control Panel->[Add/Remove] Programs is a convenient way to +check or modify your existing install.) + +.. _postinstallation-script: + +The Postinstallation script +--------------------------- + +Starting with Python 2.3, a postinstallation script can be specified with the +:option:`!--install-script` option. The basename of the script must be +specified, and the script filename must also be listed in the scripts argument +to the setup function. + +This script will be run at installation time on the target system after all the +files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at +uninstallation time before the files are removed with ``argv[1]`` set to +:option:`!-remove`. + +The installation script runs embedded in the windows installer, every output +(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be +displayed in the GUI after the script has finished. + +Some functions especially useful in this context are available as additional +built-in functions in the installation script. + + +.. function:: directory_created(path) + file_created(path) + + These functions should be called when a directory or file is created by the + postinstall script at installation time. It will register *path* with the + uninstaller, so that it will be removed when the distribution is uninstalled. + To be safe, directories are only removed if they are empty. + + +.. function:: get_special_folder_path(csidl_string) + + This function can be used to retrieve special folder locations on Windows like + the Start Menu or the Desktop. It returns the full path to the folder. + *csidl_string* must be one of the following strings:: + + "CSIDL_APPDATA" + + "CSIDL_COMMON_STARTMENU" + "CSIDL_STARTMENU" + + "CSIDL_COMMON_DESKTOPDIRECTORY" + "CSIDL_DESKTOPDIRECTORY" + + "CSIDL_COMMON_STARTUP" + "CSIDL_STARTUP" + + "CSIDL_COMMON_PROGRAMS" + "CSIDL_PROGRAMS" + + "CSIDL_FONTS" + + If the folder cannot be retrieved, :exc:`OSError` is raised. + + Which folders are available depends on the exact Windows version, and probably + also the configuration. For details refer to Microsoft's documentation of the + :c:func:`SHGetSpecialFolderPath` function. + + +.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) + + This function creates a shortcut. *target* is the path to the program to be + started by the shortcut. *description* is the description of the shortcut. + *filename* is the title of the shortcut that the user will see. *arguments* + specifies the command line arguments, if any. *workdir* is the working directory + for the program. *iconpath* is the file containing the icon for the shortcut, + and *iconindex* is the index of the icon in the file *iconpath*. Again, for + details consult the Microsoft documentation for the :class:`IShellLink` + interface. diff --git a/docs/deprecated/distutils/commandref.rst b/docs/deprecated/distutils/commandref.rst new file mode 100644 index 00000000..d02b38c3 --- /dev/null +++ b/docs/deprecated/distutils/commandref.rst @@ -0,0 +1,103 @@ +.. _reference: + +***************** +Command Reference +***************** + +.. include:: ./_setuptools_disclaimer.rst + +.. % \section{Building modules: the \protect\command{build} command family} +.. % \label{build-cmds} +.. % \subsubsection{\protect\command{build}} +.. % \label{build-cmd} +.. % \subsubsection{\protect\command{build\_py}} +.. % \label{build-py-cmd} +.. % \subsubsection{\protect\command{build\_ext}} +.. % \label{build-ext-cmd} +.. % \subsubsection{\protect\command{build\_clib}} +.. % \label{build-clib-cmd} + + +.. _install-cmd: + +Installing modules: the :command:`install` command family +========================================================= + +The install command ensures that the build commands have been run and then runs +the subcommands :command:`install_lib`, :command:`install_data` and +:command:`install_scripts`. + +.. % \subsubsection{\protect\command{install\_lib}} +.. % \label{install-lib-cmd} + + +.. _install-data-cmd: + +:command:`install_data` +----------------------- + +This command installs all data files provided with the distribution. + + +.. _install-scripts-cmd: + +:command:`install_scripts` +-------------------------- + +This command installs all (Python) scripts in the distribution. + +.. % \subsection{Cleaning up: the \protect\command{clean} command} +.. % \label{clean-cmd} + + +.. _sdist-cmd: + +Creating a source distribution: the :command:`sdist` command +============================================================ + +.. XXX fragment moved down from above: needs context! + +The manifest template commands are: + ++-------------------------------------------+-----------------------------------------------+ +| Command | Description | ++===========================================+===============================================+ +| :command:`include pat1 pat2 ...` | include all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`prune dir` | exclude all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ +| :command:`graft dir` | include all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ + +The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of +regular filename characters, ``?`` matches any single regular filename +character, and ``[range]`` matches any of the characters in *range* (e.g., +``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename +character" is platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon. + +.. XXX Windows support not there yet + +.. % \section{Creating a built distribution: the +.. % \protect\command{bdist} command family} +.. % \label{bdist-cmds} + +.. % \subsection{\protect\command{bdist}} +.. % \subsection{\protect\command{bdist\_dumb}} +.. % \subsection{\protect\command{bdist\_rpm}} diff --git a/docs/deprecated/distutils/configfile.rst b/docs/deprecated/distutils/configfile.rst new file mode 100644 index 00000000..ab199dca --- /dev/null +++ b/docs/deprecated/distutils/configfile.rst @@ -0,0 +1,144 @@ +.. _setup-config: + +************************************ +Writing the Setup Configuration File +************************************ + +.. include:: ./_setuptools_disclaimer.rst + +Often, it's not possible to write down everything needed to build a distribution +*a priori*: you may need to get some information from the user, or from the +user's system, in order to proceed. As long as that information is fairly +simple---a list of directories to search for C header files or libraries, for +example---then providing a configuration file, :file:`setup.cfg`, for users to +edit is a cheap and easy way to solicit it. Configuration files also let you +provide default values for any command option, which the installer can then +override either on the command-line or by editing the config file. + +The setup configuration file is a useful middle-ground between the setup +script---which, ideally, would be opaque to installers [#]_---and the command-line to +the setup script, which is outside of your control and entirely up to the +installer. In fact, :file:`setup.cfg` (and any other Distutils configuration +files present on the target system) are processed after the contents of the +setup script, but before the command-line. This has several useful +consequences: + +.. % (If you have more advanced needs, such as determining which extensions +.. % to build based on what capabilities are present on the target system, +.. % then you need the Distutils ``auto-configuration'' facility. This +.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature +.. % or stable enough yet for real-world use.) + +* installers can override some of what you put in :file:`setup.py` by editing + :file:`setup.cfg` + +* you can provide non-standard defaults for options that are not easily set in + :file:`setup.py` + +* installers can override anything in :file:`setup.cfg` using the command-line + options to :file:`setup.py` or by pointing :envvar:`DIST_EXTRA_CONFIG` + to another configuration file + +The basic syntax of the configuration file is simple: + +.. code-block:: ini + + [command] + option=value + ... + +where *command* is one of the Distutils commands (e.g. :command:`build_py`, +:command:`install`), and *option* is one of the options that command supports. +Any number of options can be supplied for each command, and any number of +command sections can be included in the file. Blank lines are ignored, as are +comments, which run from a ``'#'`` character until the end of the line. Long +option values can be split across multiple lines simply by indenting the +continuation lines. + +You can find out the list of options supported by a particular command with the +universal :option:`!--help` option, e.g. + +.. code-block:: shell-session + + $ python setup.py --help build_ext + [...] + Options for 'build_ext' command: + --build-lib (-b) directory for compiled extension modules + --build-temp (-t) directory for temporary files (build by-products) + --inplace (-i) ignore build-lib and put compiled extensions into the + source directory alongside your pure Python modules + --include-dirs (-I) list of directories to search for header files + --define (-D) C preprocessor macros to define + --undef (-U) C preprocessor macros to undefine + --swig-opts list of SWIG command line options + [...] + +Note that an option spelled :option:`!--foo-bar` on the command-line is spelled +``foo_bar`` in configuration files. + +.. _distutils-build-ext-inplace: + +For example, say you want your extensions to be built "in-place"---that is, you +have an extension ``pkg.ext``, and you want the compiled extension file +(:file:`ext.so` on Unix, say) to be put in the same source directory as your +pure Python modules ``pkg.mod1`` and ``pkg.mod2``. You can always use the +:option:`!--inplace` option on the command-line to ensure this: + +.. code-block:: sh + + python setup.py build_ext --inplace + +But this requires that you always specify the :command:`build_ext` command +explicitly, and remember to provide :option:`!--inplace`. An easier way is to +"set and forget" this option, by encoding it in :file:`setup.cfg`, the +configuration file for this distribution: + +.. code-block:: ini + + [build_ext] + inplace=1 + +This will affect all builds of this module distribution, whether or not you +explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in +your source distribution, it will also affect end-user builds---which is +probably a bad idea for this option, since always building extensions in-place +would break installation of the module distribution. In certain peculiar cases, +though, modules are built right in their installation directory, so this is +conceivably a useful ability. (Distributing extensions that expect to be built +in their installation directory is almost always a bad idea, though.) + +Another example: certain commands take a lot of options that don't change from +run to run; for example, :command:`bdist_rpm` needs to know everything required +to generate a "spec" file for creating an RPM distribution. Some of this +information comes from the setup script, and some is automatically generated by +the Distutils (such as the list of files installed). But some of it has to be +supplied as options to :command:`bdist_rpm`, which would be very tedious to do +on the command-line for every run. Hence, here is a snippet from the Distutils' +own :file:`setup.cfg`: + +.. code-block:: ini + + [bdist_rpm] + release = 1 + packager = Greg Ward <gward@python.net> + doc_files = CHANGES.txt + README.txt + USAGE.txt + doc/ + examples/ + +Note that the ``doc_files`` option is simply a whitespace-separated string +split across multiple lines for readability. + + +.. seealso:: + + :ref:`inst-config-syntax` in "Installing Python Modules" + More information on the configuration files is available in the manual for + system administrators. + + +.. rubric:: Footnotes + +.. [#] This ideal probably won't be achieved until auto-configuration is fully + supported by the Distutils. diff --git a/docs/deprecated/distutils/examples.rst b/docs/deprecated/distutils/examples.rst new file mode 100644 index 00000000..00eef73f --- /dev/null +++ b/docs/deprecated/distutils/examples.rst @@ -0,0 +1,338 @@ +.. _distutils_examples: + +****************** +Distutils Examples +****************** + +.. include:: ./_setuptools_disclaimer.rst + +This chapter provides a number of basic examples to help get started with +distutils. Additional information about using distutils can be found in the +Distutils Cookbook. + + +.. seealso:: + + `Distutils Cookbook <https://wiki.python.org/moin/Distutils/Cookbook>`_ + Collection of recipes showing how to achieve more control over distutils. + + +.. _pure-mod: + +Pure Python distribution (by module) +==================================== + +If you're just distributing a couple of modules, especially if they don't live +in a particular package, you can specify them individually using the +``py_modules`` option in the setup script. + +In the simplest case, you'll have two files to worry about: a setup script and +the single module you're distributing, :file:`foo.py` in this example:: + + <root>/ + setup.py + foo.py + +(In all diagrams in this section, *<root>* will refer to the distribution root +directory.) A minimal setup script to describe this situation would be:: + + from distutils.core import setup + setup(name='foo', + version='1.0', + py_modules=['foo'], + ) + +Note that the name of the distribution is specified independently with the +``name`` option, and there's no rule that says it has to be the same as +the name of the sole module in the distribution (although that's probably a good +convention to follow). However, the distribution name is used to generate +filenames, so you should stick to letters, digits, underscores, and hyphens. + +Since ``py_modules`` is a list, you can of course specify multiple +modules, eg. if you're distributing modules ``foo`` and ``bar``, your +setup might look like this:: + + <root>/ + setup.py + foo.py + bar.py + +and the setup script might be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + py_modules=['foo', 'bar'], + ) + +You can put module source files into another directory, but if you have enough +modules to do that, it's probably easier to specify modules by package rather +than listing them individually. + + +.. _pure-pkg: + +Pure Python distribution (by package) +===================================== + +If you have more than a couple of modules to distribute, especially if they are +in multiple packages, it's probably easier to specify whole packages rather than +individual modules. This works even if your modules are not in a package; you +can just tell the Distutils to process modules from the root package, and that +works the same as any other package (except that you don't have to have an +:file:`__init__.py` file). + +The setup script from the last example could also be written as :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=[''], + ) + +(The empty string stands for the root package.) + +If those two files are moved into a subdirectory, but remain in the root +package, e.g.:: + + <root>/ + setup.py + src/ foo.py + bar.py + +then you would still specify the root package, but you have to tell the +Distutils where source files in the root package live:: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'': 'src'}, + packages=[''], + ) + +More typically, though, you will want to distribute multiple modules in the same +package (or in sub-packages). For example, if the ``foo`` and ``bar`` +modules belong in package ``foobar``, one way to layout your source tree is +:: + + <root>/ + setup.py + foobar/ + __init__.py + foo.py + bar.py + +This is in fact the default layout expected by the Distutils, and the one that +requires the least work to describe in your setup script:: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=['foobar'], + ) + +If you want to put modules in directories not named for their package, then you +need to use the ``package_dir`` option again. For example, if the +:file:`src` directory holds modules in the ``foobar`` package:: + + <root>/ + setup.py + src/ + __init__.py + foo.py + bar.py + +an appropriate setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'foobar': 'src'}, + packages=['foobar'], + ) + +Or, you might put modules from your main package right in the distribution +root:: + + <root>/ + setup.py + __init__.py + foo.py + bar.py + +in which case your setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'foobar': ''}, + packages=['foobar'], + ) + +(The empty string also stands for the current directory.) + +If you have sub-packages, they must be explicitly listed in ``packages``, +but any entries in ``package_dir`` automatically extend to sub-packages. +(In other words, the Distutils does *not* scan your source tree, trying to +figure out which directories correspond to Python packages by looking for +:file:`__init__.py` files.) Thus, if the default layout grows a sub-package:: + + <root>/ + setup.py + foobar/ + __init__.py + foo.py + bar.py + subfoo/ + __init__.py + blah.py + +then the corresponding setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=['foobar', 'foobar.subfoo'], + ) + + +.. _single-ext: + +Single extension module +======================= + +Extension modules are specified using the ``ext_modules`` option. +``package_dir`` has no effect on where extension source files are found; +it only affects the source for pure Python modules. The simplest case, a +single extension module in a single C source file, is:: + + <root>/ + setup.py + foo.c + +If the ``foo`` extension belongs in the root package, the setup script for +this could be :: + + from distutils.core import setup + from distutils.extension import Extension + setup(name='foobar', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) + +If the extension actually belongs in a package, say ``foopkg``, then + +With exactly the same source tree layout, this extension can be put in the +``foopkg`` package simply by changing the name of the extension:: + + from distutils.core import setup + from distutils.extension import Extension + setup(name='foobar', + version='1.0', + ext_modules=[Extension('foopkg.foo', ['foo.c'])], + ) + +Checking a package +================== + +The ``check`` command allows you to verify if your package meta-data +meet the minimum requirements to build a distribution. + +To run it, just call it using your :file:`setup.py` script. If something is +missing, ``check`` will display a warning. + +Let's take an example with a simple script:: + + from distutils.core import setup + + setup(name='foobar') + +Running the ``check`` command will display some warnings: + +.. code-block:: shell-session + + $ python setup.py check + running check + warning: check: missing required meta-data: version + + +If you use the reStructuredText syntax in the ``long_description`` field and +`docutils`_ is installed you can check if the syntax is fine with the +``check`` command, using the ``restructuredtext`` option. + +For example, if the :file:`setup.py` script is changed like this:: + + from distutils.core import setup + + desc = """\ + My description + ============== + + This is the description of the ``foobar`` package. + """ + + setup(name='foobar', version='1', author='tarek', + author_email='tarek@ziade.org', + url='http://example.com', long_description=desc) + +Where the long description is broken, ``check`` will be able to detect it +by using the :mod:`docutils` parser: + +.. code-block:: shell-session + + $ python setup.py check --restructuredtext + running check + warning: check: Title underline too short. (line 2) + warning: check: Could not finish the parsing. + +Reading the metadata +===================== + +The :func:`distutils.core.setup` function provides a command-line interface +that allows you to query the metadata fields of a project through the +``setup.py`` script of a given project: + +.. code-block:: shell-session + + $ python setup.py --name + distribute + +This call reads the ``name`` metadata by running the +:func:`distutils.core.setup` function. Although, when a source or binary +distribution is created with Distutils, the metadata fields are written +in a static file called :file:`PKG-INFO`. When a Distutils-based project is +installed in Python, the :file:`PKG-INFO` file is copied alongside the modules +and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, +where ``NAME`` is the name of the project, ``VERSION`` its version as defined +in the Metadata, and ``pyX.X`` the major and minor version of Python like +``2.7`` or ``3.2``. + +You can read back this static file, by using the +:class:`distutils.dist.DistributionMetadata` class and its +:func:`~distutils.dist.DistributionMetadata.read_pkg_file` method:: + + >>> from distutils.dist import DistributionMetadata + >>> metadata = DistributionMetadata() + >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info')) + >>> metadata.name + 'distribute' + >>> metadata.version + '0.6.8' + >>> metadata.description + 'Easily download, build, install, upgrade, and uninstall Python packages' + +Notice that the class can also be instantiated with a metadata file path to +loads its values:: + + >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' + >>> DistributionMetadata(pkg_info_path).name + 'distribute' + + +.. % \section{Multiple extension modules} +.. % \label{multiple-ext} + +.. % \section{Putting it all together} + + +.. _docutils: http://docutils.sourceforge.net diff --git a/docs/deprecated/distutils/extending.rst b/docs/deprecated/distutils/extending.rst new file mode 100644 index 00000000..fc494616 --- /dev/null +++ b/docs/deprecated/distutils/extending.rst @@ -0,0 +1,96 @@ +.. _extending-distutils: + +******************* +Extending Distutils +******************* + +.. include:: ./_setuptools_disclaimer.rst + +Distutils can be extended in various ways. Most extensions take the form of new +commands or replacements for existing commands. New commands may be written to +support new types of platform-specific packaging, for example, while +replacements for existing commands may be made to modify details of how the +command operates on a package. + +Most extensions of the distutils are made within :file:`setup.py` scripts that +want to modify existing commands; many simply add a few file extensions that +should be copied into packages in addition to :file:`.py` files as a +convenience. + +Most distutils command implementations are subclasses of the +:class:`distutils.cmd.Command` class. New commands may directly inherit from +:class:`~distutils.cmd.Command`, while replacements often derive from :class:`~distutils.cmd.Command` +indirectly, directly subclassing the command they are replacing. Commands are +required to derive from :class:`~distutils.cmd.Command`. + +.. % \section{Extending existing commands} +.. % \label{extend-existing} + +.. % \section{Writing new commands} +.. % \label{new-commands} +.. % \XXX{Would an uninstall command be a good example here?} + + +Integrating new commands +======================== + +There are different ways to integrate new command implementations into +distutils. The most difficult is to lobby for the inclusion of the new features +in distutils itself, and wait for (and require) a version of Python that +provides that support. This is really hard for many reasons. + +The most common, and possibly the most reasonable for most needs, is to include +the new implementations with your :file:`setup.py` script, and cause the +:func:`distutils.core.setup` function use them:: + + from distutils.command.build_py import build_py as _build_py + from distutils.core import setup + + class build_py(_build_py): + """Specialized Python source builder.""" + + # implement whatever needs to be different... + + setup(cmdclass={'build_py': build_py}, + ...) + +This approach is most valuable if the new implementations must be used to use a +particular package, as everyone interested in the package will need to have the +new command implementation. + +Beginning with Python 2.4, a third option is available, intended to allow new +commands to be added which can support existing :file:`setup.py` scripts without +requiring modifications to the Python installation. This is expected to allow +third-party extensions to provide support for additional packaging systems, but +the commands can be used for anything distutils commands can be used for. A new +configuration option, ``command_packages`` (command-line option +:option:`!--command-packages`), can be used to specify additional packages to be +searched for modules implementing commands. Like all distutils options, this +can be specified on the command line or in a configuration file. This option +can only be set in the ``[global]`` section of a configuration file, or before +any commands on the command line. If set in a configuration file, it can be +overridden from the command line; setting it to an empty string on the command +line causes the default to be used. This should never be set in a configuration +file provided with a package. + +This new option can be used to add any number of packages to the list of +packages searched for command implementations; multiple package names should be +separated by commas. When not specified, the search is only performed in the +:mod:`distutils.command` package. When :file:`setup.py` is run with the option +``--command-packages distcmds,buildcmds``, however, the packages +:mod:`distutils.command`, ``distcmds``, and ``buildcmds`` will be searched +in that order. New commands are expected to be implemented in modules of the +same name as the command by classes sharing the same name. Given the example +command line option above, the command :command:`bdist_openpkg` could be +implemented by the class ``distcmds.bdist_openpkg.bdist_openpkg`` or +``buildcmds.bdist_openpkg.bdist_openpkg``. + + +Adding new distribution types +============================= + +Commands that create distributions (files in the :file:`dist/` directory) need +to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that +:command:`upload` can upload it to PyPI. The *filename* in the pair contains no +path information, only the name of the file itself. In dry-run mode, pairs +should still be added to represent what would have been created. diff --git a/docs/deprecated/distutils/index.rst b/docs/deprecated/distutils/index.rst new file mode 100644 index 00000000..1f72a255 --- /dev/null +++ b/docs/deprecated/distutils/index.rst @@ -0,0 +1,42 @@ +.. _distutils-index: + +############################################## + Distributing Python Modules (Legacy version) +############################################## + +:Authors: Greg Ward, Anthony Baxter +:Email: distutils-sig@python.org + +.. seealso:: + + :ref:`distributing-index` + The up to date module distribution documentations + +.. include:: ./_setuptools_disclaimer.rst + +.. note:: + + This guide only covers the basic tools for building and distributing + extensions that are provided as part of this version of Python. Third party + tools offer easier to use and more secure alternatives. Refer to the `quick + recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__ + in the Python Packaging User Guide for more information. + +This document describes the Python Distribution Utilities ("Distutils") from +the module developer's point of view, describing the underlying capabilities +that ``setuptools`` builds on to allow Python developers to make Python modules +and extensions readily available to a wider audience. + +.. toctree:: + :maxdepth: 2 + :numbered: + + introduction.rst + setupscript.rst + configfile.rst + sourcedist.rst + builtdist.rst + examples.rst + extending.rst + commandref.rst + apiref.rst diff --git a/docs/deprecated/distutils/introduction.rst b/docs/deprecated/distutils/introduction.rst new file mode 100644 index 00000000..58a31283 --- /dev/null +++ b/docs/deprecated/distutils/introduction.rst @@ -0,0 +1,203 @@ +.. _distutils-intro: + +**************************** +An Introduction to Distutils +**************************** + +.. include:: ./_setuptools_disclaimer.rst + +This document covers using the Distutils to distribute your Python modules, +concentrating on the role of developer/distributor: if you're looking for +information on installing Python modules, you should refer to the +:ref:`install-index` chapter. + + +.. _distutils-concepts: + +Concepts & Terminology +====================== + +Using the Distutils is quite simple, both for module developers and for +users/administrators installing third-party modules. As a developer, your +responsibilities (apart from writing solid, well-documented and well-tested +code, of course!) are: + +* write a setup script (:file:`setup.py` by convention) + +* (optional) write a setup configuration file + +* create a source distribution + +* (optional) create one or more built (binary) distributions + +Each of these tasks is covered in this document. + +Not all module developers have access to a multitude of platforms, so it's not +always feasible to expect them to create a multitude of built distributions. It +is hoped that a class of intermediaries, called *packagers*, will arise to +address this need. Packagers will take source distributions released by module +developers, build them on one or more platforms, and release the resulting built +distributions. Thus, users on the most popular platforms will be able to +install most popular Python module distributions in the most natural way for +their platform, without having to run a single setup script or compile a line of +code. + + +.. _distutils-simple-example: + +A Simple Example +================ + +The setup script is usually quite simple, although since it's written in Python, +there are no arbitrary limits to what you can do with it, though you should be +careful about putting arbitrarily expensive operations in your setup script. +Unlike, say, Autoconf-style configure scripts, the setup script may be run +multiple times in the course of building and installing your module +distribution. + +If all you want to do is distribute a module called ``foo``, contained in a +file :file:`foo.py`, then your setup script can be as simple as this:: + + from distutils.core import setup + setup(name='foo', + version='1.0', + py_modules=['foo'], + ) + +Some observations: + +* most information that you supply to the Distutils is supplied as keyword + arguments to the :func:`~distutils.core.setup` function + +* those keyword arguments fall into two categories: package metadata (name, + version number) and information about what's in the package (a list of pure + Python modules, in this case) + +* modules are specified by module name, not filename (the same will hold true + for packages and extensions) + +* it's recommended that you supply a little more metadata, in particular your + name, email address and a URL for the project (see section :ref:`setup-script` + for an example) + +To create a source distribution for this module, you would create a setup +script, :file:`setup.py`, containing the above code, and run this command from a +terminal:: + + python setup.py sdist + +For Windows, open a command prompt window (:menuselection:`Start --> +Accessories`) and change the command to:: + + setup.py sdist + +:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows) +containing your setup script :file:`setup.py`, and your module :file:`foo.py`. +The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and +will unpack into a directory :file:`foo-1.0`. + +If an end-user wishes to install your ``foo`` module, all they have to do is +download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the +:file:`foo-1.0` directory---run :: + + python setup.py install + +which will ultimately copy :file:`foo.py` to the appropriate directory for +third-party modules in their Python installation. + +This simple example demonstrates some fundamental concepts of the Distutils. +First, both developers and installers have the same basic user interface, i.e. +the setup script. The difference is which Distutils *commands* they use: the +:command:`sdist` command is almost exclusively for module developers, while +:command:`install` is more often for installers (although most developers will +want to install their own code occasionally). + +Other useful built distribution formats are RPM, implemented by the +:command:`bdist_rpm` command, Solaris :program:`pkgtool` +(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall` +(:command:`bdist_sdux`). For example, the following command will create an RPM +file called :file:`foo-1.0.noarch.rpm`:: + + python setup.py bdist_rpm + +(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore +this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or +Mandrake Linux.) + +You can find out what distribution formats are available at any time by running +:: + + python setup.py bdist --help-formats + + +.. _python-terms: + +General Python terminology +========================== + +If you're reading this document, you probably have a good idea of what modules, +extensions, and so forth are. Nevertheless, just to be sure that everyone is +operating from a common starting point, we offer the following glossary of +common Python terms: + +module + the basic unit of code reusability in Python: a block of code imported by some + other code. Three types of modules concern us here: pure Python modules, + extension modules, and packages. + +pure Python module + a module written in Python and contained in a single :file:`.py` file (and + possibly associated :file:`.pyc` files). Sometimes referred to as a + "pure module." + +extension module + a module written in the low-level language of the Python implementation: C/C++ + for Python, Java for Jython. Typically contained in a single dynamically + loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python + extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python + extensions on Windows, or a Java class file for Jython extensions. (Note that + currently, the Distutils only handles C/C++ extensions for Python.) + +package + a module that contains other modules; typically contained in a directory in the + filesystem and distinguished from other directories by the presence of a file + :file:`__init__.py`. + +root package + the root of the hierarchy of packages. (This isn't really a package, since it + doesn't have an :file:`__init__.py` file. But we have to call it something.) + The vast majority of the standard library is in the root package, as are many + small, standalone third-party modules that don't belong to a larger module + collection. Unlike regular packages, modules in the root package can be found in + many directories: in fact, every directory listed in ``sys.path`` contributes + modules to the root package. + + +.. _distutils-term: + +Distutils-specific terminology +============================== + +The following terms apply more specifically to the domain of distributing Python +modules using the Distutils: + +module distribution + a collection of Python modules distributed together as a single downloadable + resource and meant to be installed *en masse*. Examples of some well-known + module distributions are NumPy, SciPy, Pillow, + or mxBase. (This would be called a *package*, except that term is + already taken in the Python context: a single module distribution may contain + zero, one, or many Python packages.) + +pure module distribution + a module distribution that contains only pure Python modules and packages. + Sometimes referred to as a "pure distribution." + +non-pure module distribution + a module distribution that contains at least one extension module. Sometimes + referred to as a "non-pure distribution." + +distribution root + the top-level directory of your source tree (or source distribution); the + directory where :file:`setup.py` exists. Generally :file:`setup.py` will be + run from this directory. diff --git a/docs/deprecated/distutils/packageindex.rst b/docs/deprecated/distutils/packageindex.rst new file mode 100644 index 00000000..ccb9a598 --- /dev/null +++ b/docs/deprecated/distutils/packageindex.rst @@ -0,0 +1,16 @@ +:orphan: + +.. _package-index: + +******************************* +The Python Package Index (PyPI) +******************************* + +The `Python Package Index (PyPI)`_ stores metadata describing distributions +packaged with distutils and other publishing tools, as well the distribution +archives themselves. + +References to up to date PyPI documentation can be found at +:ref:`publishing-python-packages`. + +.. _Python Package Index (PyPI): https://pypi.org diff --git a/docs/deprecated/distutils/setupscript.rst b/docs/deprecated/distutils/setupscript.rst new file mode 100644 index 00000000..ec9cf34e --- /dev/null +++ b/docs/deprecated/distutils/setupscript.rst @@ -0,0 +1,715 @@ +.. _setup-script: + +************************ +Writing the Setup Script +************************ + +.. include:: ./_setuptools_disclaimer.rst + +The setup script is the centre of all activity in building, distributing, and +installing modules using the Distutils. The main purpose of the setup script is +to describe your module distribution to the Distutils, so that the various +commands that operate on your modules do the right thing. As we saw in section +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`~distutils.core.setup`, and most information +supplied to the Distutils by the module developer is supplied as keyword +arguments to :func:`~distutils.core.setup`. + +Here's a slightly more involved example, which we'll follow for the next couple +of sections: the Distutils' own setup script. (Keep in mind that although the +Distutils are included with Python 1.6 and later, they also have an independent +existence so that Python 1.5.2 users can use them to install other module +distributions. The Distutils' own setup script, shown here, is used to install +the package into Python 1.5.2.) :: + + #!/usr/bin/env python + + from distutils.core import setup + + setup(name='Distutils', + version='1.0', + description='Python Distribution Utilities', + author='Greg Ward', + author_email='gward@python.net', + url='https://www.python.org/sigs/distutils-sig/', + packages=['distutils', 'distutils.command'], + ) + +There are only two differences between this and the trivial one-file +distribution presented in section :ref:`distutils-simple-example`: more metadata, and the +specification of pure Python modules by package, rather than by module. This is +important since the Distutils consist of a couple of dozen modules split into +(so far) two packages; an explicit list of every module would be tedious to +generate and difficult to maintain. For more information on the additional +meta-data, see section :ref:`meta-data`. + +Note that any pathnames (files or directories) supplied in the setup script +should be written using the Unix convention, i.e. slash-separated. The +Distutils will take care of converting this platform-neutral representation into +whatever is appropriate on your current platform before actually using the +pathname. This makes your setup script portable across operating systems, which +of course is one of the major goals of the Distutils. In this spirit, all +pathnames in this document are slash-separated. + +This, of course, only applies to pathnames given to Distutils functions. If +you, for example, use standard Python functions such as :func:`glob.glob` or +:func:`os.listdir` to specify files, you should be careful to write portable +code instead of hardcoding path separators:: + + glob.glob(os.path.join('mydir', 'subdir', '*.html')) + os.listdir(os.path.join('mydir', 'subdir')) + + +.. _listing-packages: + +Listing whole packages +====================== + +The ``packages`` option tells the Distutils to process (build, distribute, +install, etc.) all pure Python modules found in each package mentioned in the +``packages`` list. In order to do this, of course, there has to be a +correspondence between package names and directories in the filesystem. The +default correspondence is the most obvious one, i.e. package :mod:`distutils` is +found in the directory :file:`distutils` relative to the distribution root. +Thus, when you say ``packages = ['foo']`` in your setup script, you are +promising that the Distutils will find a file :file:`foo/__init__.py` (which +might be spelled differently on your system, but you get the idea) relative to +the directory where your setup script lives. If you break this promise, the +Distutils will issue a warning but still process the broken package anyway. + +If you use a different convention to lay out your source directory, that's no +problem: you just have to supply the ``package_dir`` option to tell the +Distutils about your convention. For example, say you keep all Python source +under :file:`lib`, so that modules in the "root package" (i.e., not in any +package at all) are in :file:`lib`, modules in the ``foo`` package are in +:file:`lib/foo`, and so forth. Then you would put :: + + package_dir = {'': 'lib'} + +in your setup script. The keys to this dictionary are package names, and an +empty package name stands for the root package. The values are directory names +relative to your distribution root. In this case, when you say ``packages = +['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists. + +Another possible convention is to put the ``foo`` package right in +:file:`lib`, the ``foo.bar`` package in :file:`lib/bar`, etc. This would be +written in the setup script as :: + + package_dir = {'foo': 'lib'} + +A ``package: dir`` entry in the ``package_dir`` dictionary implicitly +applies to all packages below *package*, so the ``foo.bar`` case is +automatically handled here. In this example, having ``packages = ['foo', +'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and +:file:`lib/bar/__init__.py`. (Keep in mind that although ``package_dir`` +applies recursively, you must explicitly list all packages in +``packages``: the Distutils will *not* recursively scan your source tree +looking for any directory with an :file:`__init__.py` file.) + + +.. _listing-modules: + +Listing individual modules +========================== + +For a small module distribution, you might prefer to list all modules rather +than listing packages---especially the case of a single module that goes in the +"root package" (i.e., no package at all). This simplest case was shown in +section :ref:`distutils-simple-example`; here is a slightly more involved example:: + + py_modules = ['mod1', 'pkg.mod2'] + +This describes two modules, one of them in the "root" package, the other in the +``pkg`` package. Again, the default package/directory layout implies that +these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and +that :file:`pkg/__init__.py` exists as well. And again, you can override the +package/directory correspondence using the ``package_dir`` option. + + +.. _describing-extensions: + +Describing extension modules +============================ + +Just as writing Python extension modules is a bit more complicated than writing +pure Python modules, describing them to the Distutils is a bit more complicated. +Unlike pure modules, it's not enough just to list modules or packages and expect +the Distutils to go out and find the right files; you have to specify the +extension name, source file(s), and any compile/link requirements (include +directories, libraries to link with, etc.). + +.. XXX read over this section + +All of this is done through another keyword argument to +:func:`~distutils.core.setup`, the +``ext_modules`` option. ``ext_modules`` is just a list of +:class:`~distutils.core.Extension` instances, each of which describes a +single extension module. +Suppose your distribution includes a single extension, called ``foo`` and +implemented by :file:`foo.c`. If no additional instructions to the +compiler/linker are needed, describing this extension is quite simple:: + + Extension('foo', ['foo.c']) + +The :class:`~distutils.extension.Extension` class can be imported from :mod:`distutils.core` along +with :func:`~distutils.core.setup`. Thus, the setup script for a module distribution that +contains only this one extension and nothing else might be:: + + from distutils.core import setup, Extension + setup(name='foo', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) + +The :class:`~distutils.extension.Extension` class (actually, the underlying extension-building +machinery implemented by the :command:`build_ext` command) supports a great deal +of flexibility in describing Python extensions, which is explained in the +following sections. + + +Extension names and packages +---------------------------- + +The first argument to the :class:`~distutils.core.Extension` constructor is +always the name of the extension, including any package names. For example, :: + + Extension('foo', ['src/foo1.c', 'src/foo2.c']) + +describes an extension that lives in the root package, while :: + + Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) + +describes the same extension in the ``pkg`` package. The source files and +resulting object code are identical in both cases; the only difference is where +in the filesystem (and therefore where in Python's namespace hierarchy) the +resulting extension lives. + +If you have a number of extensions all in the same package (or all under the +same base package), use the ``ext_package`` keyword argument to +:func:`~distutils.core.setup`. For example, :: + + setup(..., + ext_package='pkg', + ext_modules=[Extension('foo', ['foo.c']), + Extension('subpkg.bar', ['bar.c'])], + ) + +will compile :file:`foo.c` to the extension ``pkg.foo``, and +:file:`bar.c` to ``pkg.subpkg.bar``. + + +Extension source files +---------------------- + +The second argument to the :class:`~distutils.core.Extension` constructor is +a list of source +files. Since the Distutils currently only support C, C++, and Objective-C +extensions, these are normally C/C++/Objective-C source files. (Be sure to use +appropriate extensions to distinguish C++ source files: :file:`.cc` and +:file:`.cpp` seem to be recognized by both Unix and Windows compilers.) + +However, you can also include SWIG interface (:file:`.i`) files in the list; the +:command:`build_ext` command knows how to deal with SWIG extensions: it will run +SWIG on the interface file and compile the resulting C/C++ file into your +extension. + +.. XXX SWIG support is rough around the edges and largely untested! + +This warning notwithstanding, options to SWIG can be currently passed like +this:: + + setup(..., + ext_modules=[Extension('_foo', ['foo.i'], + swig_opts=['-modern', '-I../include'])], + py_modules=['foo'], + ) + +Or on the commandline like this:: + + > python setup.py build_ext --swig-opts="-modern -I../include" + +On some platforms, you can include non-source files that are processed by the +compiler and included in your extension. Currently, this just means Windows +message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for +Visual C++. These will be compiled to binary resource (:file:`.res`) files and +linked into the executable. + + +Preprocessor options +-------------------- + +Three optional arguments to :class:`~distutils.core.Extension` will help if +you need to specify include directories to search or preprocessor macros to +define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``. + +For example, if your extension requires header files in the :file:`include` +directory under your distribution root, use the ``include_dirs`` option:: + + Extension('foo', ['foo.c'], include_dirs=['include']) + +You can specify absolute directories there; if you know that your extension will +only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get +away with :: + + Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) + +You should avoid this sort of non-portable usage if you plan to distribute your +code: it's probably better to write C code like :: + + #include <X11/Xlib.h> + +If you need to include header files from some other Python extension, you can +take advantage of the fact that header files are installed in a consistent way +by the Distutils :command:`install_headers` command. For example, the Numerical +Python header files are installed (on a standard Unix installation) to +:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ +according to your platform and Python installation.) Since the Python include +directory---\ :file:`/usr/local/include/python1.5` in this case---is always +included in the search path when building Python extensions, the best approach +is to write C code like :: + + #include <Numerical/arrayobject.h> + +If you must put the :file:`Numerical` include directory right into your header +search path, though, you can find that directory using the Distutils +:mod:`distutils.sysconfig` module:: + + from distutils.sysconfig import get_python_inc + incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') + setup(..., + Extension(..., include_dirs=[incdir]), + ) + +Even though this is quite portable---it will work on any Python installation, +regardless of platform---it's probably easier to just write your C code in the +sensible way. + +You can define and undefine pre-processor macros with the ``define_macros`` and +``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)`` +tuples, where ``name`` is the name of the macro to define (a string) and +``value`` is its value: either a string or ``None``. (Defining a macro ``FOO`` +to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with +most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is +just a list of macros to undefine. + +For example:: + + Extension(..., + define_macros=[('NDEBUG', '1'), + ('HAVE_STRFTIME', None)], + undef_macros=['HAVE_FOO', 'HAVE_BAR']) + +is the equivalent of having this at the top of every C source file:: + + #define NDEBUG 1 + #define HAVE_STRFTIME + #undef HAVE_FOO + #undef HAVE_BAR + + +Library options +--------------- + +You can also specify the libraries to link against when building your extension, +and the directories to search for those libraries. The ``libraries`` option is +a list of libraries to link against, ``library_dirs`` is a list of directories +to search for libraries at link-time, and ``runtime_library_dirs`` is a list of +directories to search for shared (dynamically loaded) libraries at run-time. + +For example, if you need to link against libraries known to be in the standard +library search path on target systems :: + + Extension(..., + libraries=['gdbm', 'readline']) + +If you need to link with libraries in a non-standard location, you'll have to +include the location in ``library_dirs``:: + + Extension(..., + library_dirs=['/usr/X11R6/lib'], + libraries=['X11', 'Xt']) + +(Again, this sort of non-portable construct should be avoided if you intend to +distribute your code.) + +.. XXX Should mention clib libraries here or somewhere else! + + +Other options +------------- + +There are still some other options which can be used to handle special cases. + +The ``optional`` option is a boolean; if it is true, +a build failure in the extension will not abort the build process, but +instead simply not install the failing extension. + +The ``extra_objects`` option is a list of object files to be passed to the +linker. These files must not have extensions, as the default extension for the +compiler is used. + +``extra_compile_args`` and ``extra_link_args`` can be used to +specify additional command line options for the respective compiler and linker +command lines. + +``export_symbols`` is only useful on Windows. It can contain a list of +symbols (functions or variables) to be exported. This option is not needed when +building compiled extensions: Distutils will automatically add ``initmodule`` +to the list of exported symbols. + +The ``depends`` option is a list of files that the extension depends on +(for example header files). The build command will call the compiler on the +sources to rebuild extension if any on this files has been modified since the +previous build. + +Relationships between Distributions and Packages +================================================ + +A distribution may relate to packages in three specific ways: + +#. It can require packages or modules. + +#. It can provide packages or modules. + +#. It can obsolete packages or modules. + +These relationships can be specified using keyword arguments to the +:func:`distutils.core.setup` function. + +Dependencies on other Python modules and packages can be specified by supplying +the *requires* keyword argument to :func:`~distutils.core.setup`. The +value must be a list of +strings. Each string specifies a package that is required, and optionally what +versions are sufficient. + +To specify that any version of a module or package is required, the string +should consist entirely of the module or package name. Examples include +``'mymodule'`` and ``'xml.parsers.expat'``. + +If specific versions are required, a sequence of qualifiers can be supplied in +parentheses. Each qualifier may consist of a comparison operator and a version +number. The accepted comparison operators are:: + + < > == + <= >= != + +These can be combined by using multiple qualifiers separated by commas (and +optional whitespace). In this case, all of the qualifiers must be matched; a +logical AND is used to combine the evaluations. + +Let's look at a bunch of examples: + ++-------------------------+----------------------------------------------+ +| Requires Expression | Explanation | ++=========================+==============================================+ +| ``==1.0`` | Only version ``1.0`` is compatible | ++-------------------------+----------------------------------------------+ +| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` | +| | is compatible, except ``1.5.1`` | ++-------------------------+----------------------------------------------+ + +Now that we can specify dependencies, we also need to be able to specify what we +provide that other distributions can require. This is done using the *provides* +keyword argument to :func:`~distutils.core.setup`. The value for this keyword is a list of +strings, each of which names a Python module or package, and optionally +identifies the version. If the version is not specified, it is assumed to match +that of the distribution. + +Some examples: + ++---------------------+----------------------------------------------+ +| Provides Expression | Explanation | ++=====================+==============================================+ +| ``mypkg`` | Provide ``mypkg``, using the distribution | +| | version | ++---------------------+----------------------------------------------+ +| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of | +| | the distribution version | ++---------------------+----------------------------------------------+ + +A package can declare that it obsoletes other packages using the *obsoletes* +keyword argument. The value for this is similar to that of the *requires* +keyword: a list of strings giving module or package specifiers. Each specifier +consists of a module or package name optionally followed by one or more version +qualifiers. Version qualifiers are given in parentheses after the module or +package name. + +The versions identified by the qualifiers are those that are obsoleted by the +distribution being described. If no qualifiers are given, all versions of the +named module or package are understood to be obsoleted. + +.. _distutils-installing-scripts: + +Installing Scripts +================== + +So far we have been dealing with pure and non-pure Python modules, which are +usually not run by themselves but imported by scripts. + +Scripts are files containing Python source code, intended to be started from the +command line. Scripts don't require Distutils to do anything very complicated. +The only clever feature is that if the first line of the script starts with +``#!`` and contains the word "python", the Distutils will adjust the first line +to refer to the current interpreter location. By default, it is replaced with +the current interpreter location. The :option:`!--executable` (or :option:`!-e`) +option will allow the interpreter path to be explicitly overridden. + +The ``scripts`` option simply is a list of files to be handled in this +way. From the PyXML setup script:: + + setup(..., + scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] + ) + +.. versionchanged:: 3.1 + All the scripts will also be added to the ``MANIFEST`` file if no template is + provided. See :ref:`manifest`. + + +.. _distutils-installing-package-data: + +Installing Package Data +======================= + +Often, additional files need to be installed into a package. These files are +often data that's closely related to the package's implementation, or text files +containing documentation that might be of interest to programmers using the +package. These files are called :dfn:`package data`. + +Package data can be added to packages using the ``package_data`` keyword +argument to the :func:`~distutils.core.setup` function. The value must be a mapping from +package name to a list of relative path names that should be copied into the +package. The paths are interpreted as relative to the directory containing the +package (information from the ``package_dir`` mapping is used if appropriate); +that is, the files are expected to be part of the package in the source +directories. They may contain glob patterns as well. + +The path names may contain directory portions; any necessary directories will be +created in the installation. + +For example, if a package should contain a subdirectory with several data files, +the files can be arranged like this in the source tree:: + + setup.py + src/ + mypkg/ + __init__.py + module.py + data/ + tables.dat + spoons.dat + forks.dat + +The corresponding call to :func:`~distutils.core.setup` might be:: + + setup(..., + packages=['mypkg'], + package_dir={'mypkg': 'src/mypkg'}, + package_data={'mypkg': ['data/*.dat']}, + ) + + +.. versionchanged:: 3.1 + All the files that match ``package_data`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. + + +.. _distutils-additional-files: + +Installing Additional Files +=========================== + +The ``data_files`` option can be used to specify additional files needed +by the module distribution: configuration files, message catalogs, data files, +anything which doesn't fit in the previous categories. + +``data_files`` specifies a sequence of (*directory*, *files*) pairs in the +following way:: + + setup(..., + data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), + ('config', ['cfg/data.cfg'])], + ) + +Each (*directory*, *files*) pair in the sequence specifies the installation +directory and the files to install there. + +Each file name in *files* is interpreted relative to the :file:`setup.py` +script at the top of the package source distribution. Note that you can +specify the directory where the data files will be installed, but you cannot +rename the data files themselves. + +The *directory* should be a relative path. It is interpreted relative to the +installation prefix (Python's ``sys.prefix`` for system installations; +``site.USER_BASE`` for user installations). Distutils allows *directory* to be +an absolute installation path, but this is discouraged since it is +incompatible with the wheel packaging format. No directory information from +*files* is used to determine the final location of the installed file; only +the name of the file is used. + +You can specify the ``data_files`` options as a simple sequence of files +without specifying a target directory, but this is not recommended, and the +:command:`install` command will print a warning in this case. To install data +files directly in the target directory, an empty string should be given as the +directory. + +.. versionchanged:: 3.1 + All the files that match ``data_files`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. + + +.. _meta-data: + +Additional meta-data +==================== + +The setup script may include additional meta-data beyond the name and version. +This information includes: + ++----------------------+---------------------------+-----------------+--------+ +| Meta-Data | Description | Value | Notes | ++======================+===========================+=================+========+ +| ``name`` | name of the package | short string | \(1) | ++----------------------+---------------------------+-----------------+--------+ +| ``version`` | version of this release | short string | (1)(2) | ++----------------------+---------------------------+-----------------+--------+ +| ``author`` | package author's name | short string | \(3) | ++----------------------+---------------------------+-----------------+--------+ +| ``author_email`` | email address of the | email address | \(3) | +| | package author | | | ++----------------------+---------------------------+-----------------+--------+ +| ``maintainer`` | package maintainer's name | short string | \(3) | ++----------------------+---------------------------+-----------------+--------+ +| ``maintainer_email`` | email address of the | email address | \(3) | +| | package maintainer | | | ++----------------------+---------------------------+-----------------+--------+ +| ``url`` | home page for the package | URL | | ++----------------------+---------------------------+-----------------+--------+ +| ``description`` | short, summary | short string | | +| | description of the | | | +| | package | | | ++----------------------+---------------------------+-----------------+--------+ +| ``long_description`` | longer description of the | long string | \(4) | +| | package | | | ++----------------------+---------------------------+-----------------+--------+ +| ``download_url`` | location where the | URL | | +| | package may be downloaded | | | ++----------------------+---------------------------+-----------------+--------+ +| ``classifiers`` | a list of classifiers | list of strings | (6)(7) | ++----------------------+---------------------------+-----------------+--------+ +| ``platforms`` | a list of platforms | list of strings | (6)(8) | ++----------------------+---------------------------+-----------------+--------+ +| ``keywords`` | a list of keywords | list of strings | (6)(8) | ++----------------------+---------------------------+-----------------+--------+ +| ``license`` | license for the package | short string | \(5) | ++----------------------+---------------------------+-----------------+--------+ + +Notes: + +(1) + These fields are required. + +(2) + It is recommended that versions take the form *major.minor[.patch[.sub]]*. + +(3) + If maintainer is provided and author is not, distutils lists maintainer as + the author in :file:`PKG-INFO`. + +(4) + The ``long_description`` field is used by PyPI when you publish a package, + to build its project page. + +(5) + The ``license`` field is a text indicating the license covering the + package where the license is not a selection from the "License" Trove + classifiers. See the ``Classifier`` field. Notice that + there's a ``licence`` distribution option which is deprecated but still + acts as an alias for ``license``. + +(6) + This field must be a list. + +(7) + The valid classifiers are listed on + `PyPI <https://pypi.org/classifiers>`_. + +(8) + To preserve backward compatibility, this field also accepts a string. If + you pass a comma-separated string ``'foo, bar'``, it will be converted to + ``['foo', 'bar']``, Otherwise, it will be converted to a list of one + string. + +'short string' + A single line of text, not more than 200 characters. + +'long string' + Multiple lines of plain text in reStructuredText format (see + http://docutils.sourceforge.net/). + +'list of strings' + See below. + +Encoding the version information is an art in itself. Python packages generally +adhere to the version format *major.minor[.patch][sub]*. The major number is 0 +for initial, experimental releases of software. It is incremented for releases +that represent major milestones in a package. The minor number is incremented +when important new features are added to the package. The patch number +increments when bug-fix releases are made. Additional trailing version +information is sometimes used to indicate sub-releases. These are +"a1,a2,...,aN" (for alpha releases, where functionality and API may change), +"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN" +(for final pre-release release testing). Some examples: + +0.1.0 + the first, experimental release of a package + +1.0.1a2 + the second alpha release of the first patch version of 1.0 + +``classifiers`` must be specified in a list:: + + setup(..., + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Environment :: Web Environment', + 'Intended Audience :: End Users/Desktop', + 'Intended Audience :: Developers', + 'Intended Audience :: System Administrators', + 'License :: OSI Approved :: Python Software Foundation License', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: Microsoft :: Windows', + 'Operating System :: POSIX', + 'Programming Language :: Python', + 'Topic :: Communications :: Email', + 'Topic :: Office/Business', + 'Topic :: Software Development :: Bug Tracking', + ], + ) + +.. versionchanged:: 3.7 + :class:`~distutils.core.setup` now warns when ``classifiers``, ``keywords`` + or ``platforms`` fields are not specified as a list or a string. + +.. _debug-setup-script: + +Debugging the setup script +========================== + +Sometimes things go wrong, and the setup script doesn't do what the developer +wants. + +Distutils catches any exceptions when running the setup script, and print a +simple error message before the script is terminated. The motivation for this +behaviour is to not confuse administrators who don't know much about Python and +are trying to install a package. If they get a big long traceback from deep +inside the guts of Distutils, they may think the package or the Python +installation is broken because they don't read all the way down to the bottom +and see that it's a permission problem. + +On the other hand, this doesn't help the developer to find the cause of the +failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set +to anything except an empty string, and distutils will now print detailed +information about what it is doing, dump the full traceback when an exception +occurs, and print the whole command line when an external program (like a C +compiler) fails. diff --git a/docs/deprecated/distutils/sourcedist.rst b/docs/deprecated/distutils/sourcedist.rst new file mode 100644 index 00000000..0600663d --- /dev/null +++ b/docs/deprecated/distutils/sourcedist.rst @@ -0,0 +1,242 @@ +.. _source-dist: + +****************************** +Creating a Source Distribution +****************************** + +.. include:: ./_setuptools_disclaimer.rst + +As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command +to create a source distribution. In the simplest case, :: + + python setup.py sdist + +(assuming you haven't specified any :command:`sdist` options in the setup script +or config file), :command:`sdist` creates the archive of the default format for +the current platform. The default format is a gzip'ed tar file +(:file:`.tar.gz`) on Unix, and ZIP file on Windows. + +You can specify as many formats as you like using the :option:`!--formats` +option, for example:: + + python setup.py sdist --formats=gztar,zip + +to create a gzipped tarball and a zip file. The available formats are: + ++-----------+-------------------------+---------+ +| Format | Description | Notes | ++===========+=========================+=========+ +| ``zip`` | zip file (:file:`.zip`) | (1),(3) | ++-----------+-------------------------+---------+ +| ``gztar`` | gzip'ed tar file | \(2) | +| | (:file:`.tar.gz`) | | ++-----------+-------------------------+---------+ +| ``bztar`` | bzip2'ed tar file | | +| | (:file:`.tar.bz2`) | | ++-----------+-------------------------+---------+ +| ``xztar`` | xz'ed tar file | | +| | (:file:`.tar.xz`) | | ++-----------+-------------------------+---------+ +| ``ztar`` | compressed tar file | \(4) | +| | (:file:`.tar.Z`) | | ++-----------+-------------------------+---------+ +| ``tar`` | tar file (:file:`.tar`) | | ++-----------+-------------------------+---------+ + +.. versionchanged:: 3.5 + Added support for the ``xztar`` format. + +Notes: + +(1) + default on Windows + +(2) + default on Unix + +(3) + requires either external :program:`zip` utility or :mod:`zipfile` module (part + of the standard Python library since Python 1.6) + +(4) + requires the :program:`compress` program. Notice that this format is now + pending for deprecation and will be removed in the future versions of Python. + +When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``ztar`` or +``tar``), under Unix you can specify the ``owner`` and ``group`` names +that will be set for each member of the archive. + +For example, if you want all files of the archive to be owned by root:: + + python setup.py sdist --owner=root --group=root + + +.. _manifest: + +Specifying the files to distribute +================================== + +If you don't supply an explicit list of files (or instructions on how to +generate one), the :command:`sdist` command puts a minimal default set into the +source distribution: + +* all Python source files implied by the ``py_modules`` and + ``packages`` options + +* all C source files mentioned in the ``ext_modules`` or + ``libraries`` options + + .. XXX getting C library sources currently broken---no + :meth:`get_source_files` method in :file:`build_clib.py`! + +* scripts identified by the ``scripts`` option + See :ref:`distutils-installing-scripts`. + +* anything that looks like a test script: :file:`test/test\*.py` (currently, the + Distutils don't do anything with test scripts except include them in source + distributions, but in the future there will be a standard for testing Python + module distributions) + +* Any of the standard README files (:file:`README`, :file:`README.txt`, + or :file:`README.rst`), :file:`setup.py` (or whatever you called your setup + script), and :file:`setup.cfg`. + +* all files that matches the ``package_data`` metadata. + See :ref:`distutils-installing-package-data`. + +* all files that matches the ``data_files`` metadata. + See :ref:`distutils-additional-files`. + +Sometimes this is enough, but usually you will want to specify additional files +to distribute. The typical way to do this is to write a *manifest template*, +called :file:`MANIFEST.in` by default. The manifest template is just a list of +instructions for how to generate your manifest file, :file:`MANIFEST`, which is +the exact list of files to include in your source distribution. The +:command:`sdist` command processes this template and generates a manifest based +on its instructions and what it finds in the filesystem. + +If you prefer to roll your own manifest file, the format is simple: one filename +per line, regular files (or symlinks to them) only. If you do supply your own +:file:`MANIFEST`, you must specify everything: the default set of files +described above does not apply in this case. + +.. versionchanged:: 3.1 + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. + +.. versionchanged:: 3.1.3 + :file:`MANIFEST` files start with a comment indicating they are generated. + Files without this comment are not overwritten or removed. + +.. versionchanged:: 3.2.2 + :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in` + exists, like it used to do. + +.. versionchanged:: 3.7 + :file:`README.rst` is now included in the list of distutils standard READMEs. + + +The manifest template has one command per line, where each command specifies a +set of files to include or exclude from the source distribution. For an +example, again we turn to the Distutils' own manifest template: + +.. code-block:: none + + include *.txt + recursive-include examples *.txt *.py + prune examples/sample?/build + +The meanings should be fairly clear: include all files in the distribution root +matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory +matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching +:file:`examples/sample?/build`. All of this is done *after* the standard +include set, so you can exclude files from the standard set with explicit +instructions in the manifest template. (Or, you can use the +:option:`!--no-defaults` option to disable the standard set entirely.) There are +several other commands available in the manifest template mini-language; see +section :ref:`sdist-cmd`. + +The order of commands in the manifest template matters: initially, we have the +list of default files as described above, and each command in the template adds +to or removes from that list of files. Once we have fully processed the +manifest template, we remove files that should not be included in the source +distribution: + +* all files in the Distutils "build" tree (default :file:`build/`) + +* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`, + :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs` + +Now we have our complete list of files, which is written to the manifest for +future reference, and then used to build the source distribution archive(s). + +You can disable the default set of included files with the +:option:`!--no-defaults` option, and you can disable the standard exclude set +with :option:`!--no-prune`. + +Following the Distutils' own manifest template, let's trace how the +:command:`sdist` command builds the list of files to include in the Distutils +source distribution: + +#. include all Python source files in the :file:`distutils` and + :file:`distutils/command` subdirectories (because packages corresponding to + those two directories were mentioned in the ``packages`` option in the + setup script---see section :ref:`setup-script`) + +#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard + files) + +#. include :file:`test/test\*.py` (standard files) + +#. include :file:`\*.txt` in the distribution root (this will find + :file:`README.txt` a second time, but such redundancies are weeded out later) + +#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree + under :file:`examples`, + +#. exclude all files in the sub-trees starting at directories matching + :file:`examples/sample?/build`\ ---this may exclude files included by the + previous two steps, so it's important that the ``prune`` command in the manifest + template comes after the ``recursive-include`` command + +#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`, + :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs` + directories + +Just like in the setup script, file and directory names in the manifest template +should always be slash-separated; the Distutils will take care of converting +them to the standard representation on your platform. That way, the manifest +template is portable across operating systems. + + +.. _manifest-options: + +Manifest-related options +======================== + +The normal course of operations for the :command:`sdist` command is as follows: + +* if the manifest file (:file:`MANIFEST` by default) exists and the first line + does not have a comment indicating it is generated from :file:`MANIFEST.in`, + then it is used as is, unaltered + +* if the manifest file doesn't exist or has been previously automatically + generated, read :file:`MANIFEST.in` and create the manifest + +* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest + with just the default file set + +* use the list of files now in :file:`MANIFEST` (either just generated or read + in) to create the source distribution archive(s) + +There are a couple of options that modify this behaviour. First, use the +:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard +"include" and "exclude" sets. + +Second, you might just want to (re)generate the manifest, but not create a source +distribution:: + + python setup.py sdist --manifest-only + +:option:`!-o` is a shortcut for :option:`!--manifest-only`. diff --git a/docs/deprecated/distutils/uploading.rst b/docs/deprecated/distutils/uploading.rst new file mode 100644 index 00000000..4c391cab --- /dev/null +++ b/docs/deprecated/distutils/uploading.rst @@ -0,0 +1,8 @@ +:orphan: + +*************************************** +Uploading Packages to the Package Index +*************************************** + +References to up to date PyPI documentation can be found at +:ref:`publishing-python-packages`. diff --git a/docs/deprecated/easy_install.rst b/docs/deprecated/easy_install.rst new file mode 100644 index 00000000..3cf3bea9 --- /dev/null +++ b/docs/deprecated/easy_install.rst @@ -0,0 +1,1079 @@ +============ +Easy Install +============ + +.. warning:: + Easy Install is deprecated. Do not use it. Instead use pip. If + you think you need Easy Install, please reach out to the PyPA + team (a ticket to pip or setuptools is fine), describing your + use-case. + +Easy Install is a python module (``easy_install``) bundled with ``setuptools`` +that lets you automatically download, build, install, and manage Python +packages. + +Please share your experiences with us! If you encounter difficulty installing +a package, please contact us via the `distutils mailing list +<http://mail.python.org/pipermail/distutils-sig/>`_. (Note: please DO NOT send +private email directly to the author of setuptools; it will be discarded. The +mailing list is a searchable archive of previously-asked and answered +questions; you should begin your research there before reporting something as a +bug -- and then do so via list discussion first.) + +(Also, if you'd like to learn about how you can use ``setuptools`` to make your +own packages work better with EasyInstall, or provide EasyInstall-like features +without requiring your users to use EasyInstall directly, you'll probably want +to check out the full documentation as well.) + +Using "Easy Install" +==================== + + +.. _installation instructions: + +Installing "Easy Install" +------------------------- + +Please see the :pypi:`setuptools` on the package index +for download links and basic installation instructions for each of the +supported platforms. + +You will need at least Python 3.5 or 2.7. An ``easy_install`` script will be +installed in the normal location for Python scripts on your platform. + +Note that the instructions on the setuptools PyPI page assume that you are +are installing to Python's primary ``site-packages`` directory. If this is +not the case, you should consult the section below on `Custom Installation +Locations`_ before installing. (And, on Windows, you should not use the +``.exe`` installer when installing to an alternate location.) + +Note that ``easy_install`` normally works by downloading files from the +internet. If you are behind an NTLM-based firewall that prevents Python +programs from accessing the net directly, you may wish to first install and use +the `APS proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such +firewalls in the same way that your web browser(s) do. + +(Alternately, if you do not wish easy_install to actually download anything, you +can restrict it from doing so with the ``--allow-hosts`` option; see the +sections on `restricting downloads with --allow-hosts`_ and `command-line +options`_ for more details.) + + +Troubleshooting +~~~~~~~~~~~~~~~ + +If EasyInstall/setuptools appears to install correctly, and you can run the +``easy_install`` command but it fails with an ``ImportError``, the most likely +cause is that you installed to a location other than ``site-packages``, +without taking any of the steps described in the `Custom Installation +Locations`_ section below. Please see that section and follow the steps to +make sure that your custom location will work correctly. Then re-install. + +Similarly, if you can run ``easy_install``, and it appears to be installing +packages, but then you can't import them, the most likely issue is that you +installed EasyInstall correctly but are using it to install packages to a +non-standard location that hasn't been properly prepared. Again, see the +section on `Custom Installation Locations`_ for more details. + + +Windows Notes +~~~~~~~~~~~~~ + +Installing setuptools will provide an ``easy_install`` command according to +the techniques described in `Executables and Launchers`_. If the +``easy_install`` command is not available after installation, that section +provides details on how to configure Windows to make the commands available. + + +Downloading and Installing a Package +------------------------------------ + +For basic use of ``easy_install``, you need only supply the filename or URL of +a source distribution or .egg file (`Python Egg`__). + +__ http://peak.telecommunity.com/DevCenter/PythonEggs + +**Example 1**. Install a package by name, searching PyPI for the latest +version, and automatically downloading, building, and installing it:: + + easy_install SQLObject + +**Example 2**. Install or upgrade a package by name and version by finding +links on a given "download page":: + + easy_install -f http://pythonpaste.org/package_index.html SQLObject + +**Example 3**. Download a source distribution from a specified URL, +automatically building and installing it:: + + easy_install http://example.com/path/to/MyPackage-1.2.3.tgz + +**Example 4**. Install an already-downloaded .egg file:: + + easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg + +**Example 5**. Upgrade an already-installed package to the latest version +listed on PyPI:: + + easy_install --upgrade PyProtocols + +**Example 6**. Install a source distribution that's already downloaded and +extracted in the current directory (New in 0.5a9):: + + easy_install . + +**Example 7**. (New in 0.6a1) Find a source distribution or Subversion +checkout URL for a package, and extract it or check it out to +``~/projects/sqlobject`` (the name will always be in all-lowercase), where it +can be examined or edited. (The package will not be installed, but it can +easily be installed with ``easy_install ~/projects/sqlobject``. See `Editing +and Viewing Source Packages`_ below for more info.):: + + easy_install --editable --build-directory ~/projects SQLObject + +**Example 7**. (New in 0.6.11) Install a distribution within your home dir:: + + easy_install --user SQLAlchemy + +Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils`` +"distribution" names), and package+version specifiers. In each case, it will +attempt to locate the latest available version that meets your criteria. + +When downloading or processing downloaded files, Easy Install recognizes +distutils source distribution files with extensions of .tgz, .tar, .tar.gz, +.tar.bz2, or .zip. And of course it handles already-built .egg +distributions as well as ``.win32.exe`` installers built using distutils. + +By default, packages are installed to the running Python installation's +``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir`` +option to specify an alternative directory, or specify an alternate location +using distutils configuration files. (See `Configuration Files`_, below.) + +By default, any scripts included with the package are installed to the running +Python installation's standard script installation location. However, if you +specify an installation directory via the command line or a config file, then +the default directory for installing scripts will be the same as the package +installation directory, to ensure that the script will have access to the +installed package. You can override this using the ``-s`` or ``--script-dir`` +option. + +Installed packages are added to an ``easy-install.pth`` file in the install +directory, so that Python will always use the most-recently-installed version +of the package. If you would like to be able to select which version to use at +runtime, you should use the ``-m`` or ``--multi-version`` option. + + +Upgrading a Package +------------------- + +You don't need to do anything special to upgrade a package: just install the +new version, either by requesting a specific version, e.g.:: + + easy_install "SomePackage==2.0" + +a version greater than the one you have now:: + + easy_install "SomePackage>2.0" + +using the upgrade flag, to find the latest available version on PyPI:: + + easy_install --upgrade SomePackage + +or by using a download page, direct download URL, or package filename:: + + easy_install -f http://example.com/downloads ExamplePackage + + easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg + + easy_install my_downloads/ExamplePackage-2.0.tgz + +If you're using ``-m`` or ``--multi-version`` , using the ``require()`` +function at runtime automatically selects the newest installed version of a +package that meets your version criteria. So, installing a newer version is +the only step needed to upgrade such packages. + +If you're installing to a directory on PYTHONPATH, or a configured "site" +directory (and not using ``-m``), installing a package automatically replaces +any previous version in the ``easy-install.pth`` file, so that Python will +import the most-recently installed version by default. So, again, installing +the newer version is the only upgrade step needed. + +If you haven't suppressed script installation (using ``--exclude-scripts`` or +``-x``), then the upgraded version's scripts will be installed, and they will +be automatically patched to ``require()`` the corresponding version of the +package, so that you can use them even if they are installed in multi-version +mode. + +``easy_install`` never actually deletes packages (unless you're installing a +package with the same name and version number as an existing package), so if +you want to get rid of older versions of a package, please see `Uninstalling +Packages`_, below. + + +Changing the Active Version +--------------------------- + +If you've upgraded a package, but need to revert to a previously-installed +version, you can do so like this:: + + easy_install PackageName==1.2.3 + +Where ``1.2.3`` is replaced by the exact version number you wish to switch to. +If a package matching the requested name and version is not already installed +in a directory on ``sys.path``, it will be located via PyPI and installed. + +If you'd like to switch to the latest installed version of ``PackageName``, you +can do so like this:: + + easy_install PackageName + +This will activate the latest installed version. (Note: if you have set any +``find_links`` via distutils configuration files, those download pages will be +checked for the latest available version of the package, and it will be +downloaded and installed if it is newer than your current version.) + +Note that changing the active version of a package will install the newly +active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is +specified. + + +Uninstalling Packages +--------------------- + +If you have replaced a package with another version, then you can just delete +the package(s) you don't need by deleting the PackageName-versioninfo.egg file +or directory (found in the installation directory). + +If you want to delete the currently installed version of a package (or all +versions of a package), you should first run:: + + easy_install -m PackageName + +This will ensure that Python doesn't continue to search for a package you're +planning to remove. After you've done this, you can safely delete the .egg +files or directories, along with any scripts you wish to remove. + + +Managing Scripts +---------------- + +Whenever you install, upgrade, or change versions of a package, EasyInstall +automatically installs the scripts for the selected package version, unless +you tell it not to with ``-x`` or ``--exclude-scripts``. If any scripts in +the script directory have the same name, they are overwritten. + +Thus, you do not normally need to manually delete scripts for older versions of +a package, unless the newer version of the package does not include a script +of the same name. However, if you are completely uninstalling a package, you +may wish to manually delete its scripts. + +EasyInstall's default behavior means that you can normally only run scripts +from one version of a package at a time. If you want to keep multiple versions +of a script available, however, you can simply use the ``--multi-version`` or +``-m`` option, and rename the scripts that EasyInstall creates. This works +because EasyInstall installs scripts as short code stubs that ``require()`` the +matching version of the package the script came from, so renaming the script +has no effect on what it executes. + +For example, suppose you want to use two versions of the ``rst2html`` tool +provided by the `docutils <http://docutils.sf.net/>`_ package. You might +first install one version:: + + easy_install -m docutils==0.3.9 + +then rename the ``rst2html.py`` to ``r2h_039``, and install another version:: + + easy_install -m docutils==0.3.10 + +This will create another ``rst2html.py`` script, this one using docutils +version 0.3.10 instead of 0.3.9. You now have two scripts, each using a +different version of the package. (Notice that we used ``-m`` for both +installations, so that Python won't lock us out of using anything but the most +recently-installed version of the package.) + + +Executables and Launchers +------------------------- + +On Unix systems, scripts are installed with as natural files with a "#!" +header and no extension and they launch under the Python version indicated in +the header. + +On Windows, there is no mechanism to "execute" files without extensions, so +EasyInstall provides two techniques to mirror the Unix behavior. The behavior +is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be +"executable" (default) or "natural". + +Regardless of the technique used, the script(s) will be installed to a Scripts +directory (by default in the Python installation directory). It is recommended +for EasyInstall that you ensure this directory is in the PATH environment +variable. The easiest way to ensure the Scripts directory is in the PATH is +to run ``Tools\Scripts\win_add2path.py`` from the Python directory. + +Note that instead of changing your ``PATH`` to include the Python scripts +directory, you can also retarget the installation location for scripts so they +go on a directory that's already on the ``PATH``. For more information see +`Command-Line Options`_ and `Configuration Files`_. During installation, +pass command line options (such as ``--script-dir``) to control where +scripts will be installed. + + +Windows Executable Launcher +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the "executable" launcher is used, EasyInstall will create a '.exe' +launcher of the same name beside each installed script (including +``easy_install`` itself). These small .exe files launch the script of the +same name using the Python version indicated in the '#!' header. + +This behavior is currently default. To force +the use of executable launchers, set ``SETUPTOOLS_LAUNCHER`` to "executable". + +Natural Script Launcher +~~~~~~~~~~~~~~~~~~~~~~~ + +EasyInstall also supports deferring to an external launcher such as +`pylauncher <https://bitbucket.org/pypa/pylauncher>`_ for launching scripts. +Enable this experimental functionality by setting the +``SETUPTOOLS_LAUNCHER`` environment variable to "natural". EasyInstall will +then install scripts as simple +scripts with a .pya (or .pyw) extension appended. If these extensions are +associated with the pylauncher and listed in the PATHEXT environment variable, +these scripts can then be invoked simply and directly just like any other +executable. This behavior may become default in a future version. + +EasyInstall uses the .pya extension instead of simply +the typical '.py' extension. This distinct extension is necessary to prevent +Python +from treating the scripts as importable modules (where name conflicts exist). +Current releases of pylauncher do not yet associate with .pya files by +default, but future versions should do so. + + +Tips & Techniques +----------------- + +Multiple Python Versions +~~~~~~~~~~~~~~~~~~~~~~~~ + +EasyInstall installs itself under two names: +``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version +used to install it. Thus, if you install EasyInstall for both Python 3.2 and +2.7, you can use the ``easy_install-3.2`` or ``easy_install-2.7`` scripts to +install packages for the respective Python version. + +Setuptools also supplies easy_install as a runnable module which may be +invoked using ``python -m easy_install`` for any Python with Setuptools +installed. + +Restricting Downloads with ``--allow-hosts`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use the ``--allow-hosts`` (``-H``) option to restrict what domains +EasyInstall will look for links and downloads on. ``--allow-hosts=None`` +prevents downloading altogether. You can also use wildcards, for example +to restrict downloading to hosts in your own intranet. See the section below +on `Command-Line Options`_ for more details on the ``--allow-hosts`` option. + +By default, there are no host restrictions in effect, but you can change this +default by editing the appropriate `configuration files`_ and adding: + +.. code-block:: ini + + [easy_install] + allow_hosts = *.myintranet.example.com,*.python.org + +The above example would then allow downloads only from hosts in the +``python.org`` and ``myintranet.example.com`` domains, unless overridden on the +command line. + + +Installing on Un-networked Machines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Just copy the eggs or source packages you need to a directory on the target +machine, then use the ``-f`` or ``--find-links`` option to specify that +directory's location. For example:: + + easy_install -H None -f somedir SomePackage + +will attempt to install SomePackage using only eggs and source packages found +in ``somedir`` and disallowing all remote access. You should of course make +sure you have all of SomePackage's dependencies available in somedir. + +If you have another machine of the same operating system and library versions +(or if the packages aren't platform-specific), you can create the directory of +eggs using a command like this:: + + easy_install -zmaxd somedir SomePackage + +This will tell EasyInstall to put zipped eggs or source packages for +SomePackage and all its dependencies into ``somedir``, without creating any +scripts or .pth files. You can then copy the contents of ``somedir`` to the +target machine. (``-z`` means zipped eggs, ``-m`` means multi-version, which +prevents .pth files from being used, ``-a`` means to copy all the eggs needed, +even if they're installed elsewhere on the machine, and ``-d`` indicates the +directory to place the eggs in.) + +You can also build the eggs from local development packages that were installed +with the ``setup.py develop`` command, by including the ``-l`` option, e.g.:: + + easy_install -zmaxld somedir SomePackage + +This will use locally-available source distributions to build the eggs. + + +Packaging Others' Projects As Eggs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Need to distribute a package that isn't published in egg form? You can use +EasyInstall to build eggs for a project. You'll want to use the ``--zip-ok``, +``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and +``-N``, respectively). Use ``-d`` or ``--install-dir`` to specify the location +where you'd like the eggs placed. By placing them in a directory that is +published to the web, you can then make the eggs available for download, either +in an intranet or to the internet at large. + +If someone distributes a package in the form of a single ``.py`` file, you can +wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL. +So, something like this:: + + easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo + +will install the package as an egg, and this:: + + easy_install -zmaxd. \ + -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo + +will create a ``.egg`` file in the current directory. + + +Creating your own Package Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to local directories and the Python Package Index, EasyInstall can +find download links on most any web page whose URL is given to the ``-f`` +(``--find-links``) option. In the simplest case, you can simply have a web +page with links to eggs or Python source packages, even an automatically +generated directory listing (such as the Apache web server provides). + +If you are setting up an intranet site for package downloads, you may want to +configure the target machines to use your download site by default, adding +something like this to their `configuration files`_: + +.. code-block:: ini + + [easy_install] + find_links = http://mypackages.example.com/somedir/ + http://turbogears.org/download/ + http://peak.telecommunity.com/dist/ + +As you can see, you can list multiple URLs separated by whitespace, continuing +on multiple lines if necessary (as long as the subsequent lines are indented. + +If you are more ambitious, you can also create an entirely custom package index +or PyPI mirror. See the ``--index-url`` option under `Command-Line Options`_, +below, and also the section on `Package Index "API"`_. + + +Password-Protected Sites +------------------------ + +If a site you want to download from is password-protected using HTTP "Basic" +authentication, you can specify your credentials in the URL, like so:: + + http://some_userid:some_password@some.example.com/some_path/ + +You can do this with both index page URLs and direct download URLs. As long +as any HTML pages read by easy_install use *relative* links to point to the +downloads, the same user ID and password will be used to do the downloading. + +Using .pypirc Credentials +------------------------- + +In additional to supplying credentials in the URL, ``easy_install`` will also +honor credentials if present in the .pypirc file. Teams maintaining a private +repository of packages may already have defined access credentials for +uploading packages according to the distutils documentation. ``easy_install`` +will attempt to honor those if present. Refer to the distutils documentation +for Python 2.5 or later for details on the syntax. + +Controlling Build Options +~~~~~~~~~~~~~~~~~~~~~~~~~ + +EasyInstall respects standard distutils `Configuration Files`_, so you can use +them to configure build options for packages that it installs from source. For +example, if you are on Windows using the MinGW compiler, you can configure the +default compiler by putting something like this: + +.. code-block:: ini + + [build] + compiler = mingw32 + +into the appropriate distutils configuration file. In fact, since this is just +normal distutils configuration, it will affect any builds using that config +file, not just ones done by EasyInstall. For example, if you add those lines +to ``distutils.cfg`` in the ``distutils`` package directory, it will be the +default compiler for *all* packages you build. See `Configuration Files`_ +below for a list of the standard configuration file locations, and links to +more documentation on using distutils configuration files. + + +Editing and Viewing Source Packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes a package's source distribution contains additional documentation, +examples, configuration files, etc., that are not part of its actual code. If +you want to be able to examine these files, you can use the ``--editable`` +option to EasyInstall, and EasyInstall will look for a source distribution +or Subversion URL for the package, then download and extract it or check it out +as a subdirectory of the ``--build-directory`` you specify. If you then wish +to install the package after editing or configuring it, you can do so by +rerunning EasyInstall with that directory as the target. + +Note that using ``--editable`` stops EasyInstall from actually building or +installing the package; it just finds, obtains, and possibly unpacks it for +you. This allows you to make changes to the package if necessary, and to +either install it in development mode using ``setup.py develop`` (if the +package uses setuptools, that is), or by running ``easy_install projectdir`` +(where ``projectdir`` is the subdirectory EasyInstall created for the +downloaded package. + +In order to use ``--editable`` (``-e`` for short), you *must* also supply a +``--build-directory`` (``-b`` for short). The project will be placed in a +subdirectory of the build directory. The subdirectory will have the same +name as the project itself, but in all-lowercase. If a file or directory of +that name already exists, EasyInstall will print an error message and exit. + +Also, when using ``--editable``, you cannot use URLs or filenames as arguments. +You *must* specify project names (and optional version requirements) so that +EasyInstall knows what directory name(s) to create. If you need to force +EasyInstall to use a particular URL or filename, you should specify it as a +``--find-links`` item (``-f`` for short), and then also specify +the project name, e.g.:: + + easy_install -eb ~/projects \ + -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \ + ctypes==0.9.6 + + +Dealing with Installation Conflicts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that +people using older versions of EasyInstall can consult it. As of version +0.6a11, installation conflicts are handled automatically without deleting the +old or system-installed packages, and without ignoring the issue. Instead, +eggs are automatically shifted to the front of ``sys.path`` using special +code added to the ``easy-install.pth`` file. So, if you are using version +0.6a11 or better of setuptools, you do not need to worry about conflicts, +and the following issues do not apply to you.) + +EasyInstall installs distributions in a "managed" way, such that each +distribution can be independently activated or deactivated on ``sys.path``. +However, packages that were not installed by EasyInstall are "unmanaged", +in that they usually live all in one directory and cannot be independently +activated or deactivated. + +As a result, if you are using EasyInstall to upgrade an existing package, or +to install a package with the same name as an existing package, EasyInstall +will warn you of the conflict. (This is an improvement over ``setup.py +install``, because the ``distutils`` just install new packages on top of old +ones, possibly combining two unrelated packages or leaving behind modules that +have been deleted in the newer version of the package.) + +EasyInstall will stop the installation if it detects a conflict +between an existing, "unmanaged" package, and a module or package in any of +the distributions you're installing. It will display a list of all of the +existing files and directories that would need to be deleted for the new +package to be able to function correctly. To proceed, you must manually +delete these conflicting files and directories and re-run EasyInstall. + +Of course, once you've replaced all of your existing "unmanaged" packages with +versions managed by EasyInstall, you won't have any more conflicts to worry +about! + + +Compressed Installation +~~~~~~~~~~~~~~~~~~~~~~~ + +EasyInstall tries to install packages in zipped form, if it can. Zipping +packages can improve Python's overall import performance if you're not using +the ``--multi-version`` option, because Python processes zipfile entries on +``sys.path`` much faster than it does directories. + +As of version 0.5a9, EasyInstall analyzes packages to determine whether they +can be safely installed as a zipfile, and then acts on its analysis. (Previous +versions would not install a package as a zipfile unless you used the +``--zip-ok`` option.) + +The current analysis approach is fairly conservative; it currently looks for: + + * Any use of the ``__file__`` or ``__path__`` variables (which should be + replaced with ``pkg_resources`` API calls) + + * Possible use of ``inspect`` functions that expect to manipulate source files + (e.g. ``inspect.getsource()``) + + * Top-level modules that might be scripts used with ``python -m`` (Python 2.4) + +If any of the above are found in the package being installed, EasyInstall will +assume that the package cannot be safely run from a zipfile, and unzip it to +a directory instead. You can override this analysis with the ``-zip-ok`` flag, +which will tell EasyInstall to install the package as a zipfile anyway. Or, +you can use the ``--always-unzip`` flag, in which case EasyInstall will always +unzip, even if its analysis says the package is safe to run as a zipfile. + +Normally, however, it is simplest to let EasyInstall handle the determination +of whether to zip or unzip, and only specify overrides when needed to work +around a problem. If you find you need to override EasyInstall's guesses, you +may want to contact the package author and the EasyInstall maintainers, so that +they can make appropriate changes in future versions. + +(Note: If a package uses ``setuptools`` in its setup script, the package author +has the option to declare the package safe or unsafe for zipped usage via the +``zip_safe`` argument to ``setup()``. If the package author makes such a +declaration, EasyInstall believes the package's author and does not perform its +own analysis. However, your command-line option, if any, will still override +the package author's choice.) + + +Reference Manual +================ + +Configuration Files +------------------- + +(New in 0.4a2) + +You may specify default options for EasyInstall using the standard +distutils configuration files, under the command heading ``easy_install``. +EasyInstall will look first for a ``setup.cfg`` file in the current directory, +then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes +and Windows, respectively), and finally a ``distutils.cfg`` file in the +``distutils`` package directory. Here's a simple example: + +.. code-block:: ini + + [easy_install] + + # set the default location to install packages + install_dir = /home/me/lib/python + + # Notice that indentation can be used to continue an option + # value; this is especially useful for the "--find-links" + # option, which tells easy_install to use download links on + # these pages before consulting PyPI: + # + find_links = http://sqlobject.org/ + http://peak.telecommunity.com/dist/ + +In addition to accepting configuration for its own options under +``[easy_install]``, EasyInstall also respects defaults specified for other +distutils commands. For example, if you don't set an ``install_dir`` for +``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]`` +command, this will become EasyInstall's default installation directory. Thus, +if you are already using distutils configuration files to set default install +locations, build options, etc., EasyInstall will respect your existing settings +until and unless you override them explicitly in an ``[easy_install]`` section. + +For more information, see also the current Python documentation on the `use and +location of distutils configuration files <https://docs.python.org/install/index.html#inst-config-files>`_. + +Notice that ``easy_install`` will use the ``setup.cfg`` from the current +working directory only if it was triggered from ``setup.py`` through the +``install_requires`` option. The standalone command will not use that file. + +Command-Line Options +-------------------- + +``--zip-ok, -z`` + Install all packages as zip files, even if they are marked as unsafe for + running as a zipfile. This can be useful when EasyInstall's analysis + of a non-setuptools package is too conservative, but keep in mind that + the package may not work correctly. (Changed in 0.5a9; previously this + option was required in order for zipped installation to happen at all.) + +``--always-unzip, -Z`` + Don't install any packages as zip files, even if the packages are marked + as safe for running as a zipfile. This can be useful if a package does + something unsafe, but not in a way that EasyInstall can easily detect. + EasyInstall's default analysis is currently very conservative, however, so + you should only use this option if you've had problems with a particular + package, and *after* reporting the problem to the package's maintainer and + to the EasyInstall maintainers. + + (Note: the ``-z/-Z`` options only affect the installation of newly-built + or downloaded packages that are not already installed in the target + directory; if you want to convert an existing installed version from + zipped to unzipped or vice versa, you'll need to delete the existing + version first, and re-run EasyInstall.) + +``--multi-version, -m`` + "Multi-version" mode. Specifying this option prevents ``easy_install`` from + adding an ``easy-install.pth`` entry for the package being installed, and + if an entry for any version the package already exists, it will be removed + upon successful installation. In multi-version mode, no specific version of + the package is available for importing, unless you use + ``pkg_resources.require()`` to put it on ``sys.path``. This can be as + simple as:: + + from pkg_resources import require + require("SomePackage", "OtherPackage", "MyPackage") + + which will put the latest installed version of the specified packages on + ``sys.path`` for you. (For more advanced uses, like selecting specific + versions and enabling optional dependencies, see the ``pkg_resources`` API + doc.) + + Changed in 0.6a10: this option is no longer silently enabled when + installing to a non-PYTHONPATH, non-"site" directory. You must always + explicitly use this option if you want it to be active. + +``--upgrade, -U`` (New in 0.5a4) + By default, EasyInstall only searches online if a project/version + requirement can't be met by distributions already installed + on sys.path or the installation directory. However, if you supply the + ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package + index and ``--find-links`` URLs before selecting a version to install. In + this way, you can force EasyInstall to use the latest available version of + any package it installs (subject to any version requirements that might + exclude such later versions). + +``--install-dir=DIR, -d DIR`` + Set the installation directory. It is up to you to ensure that this + directory is on ``sys.path`` at runtime, and to use + ``pkg_resources.require()`` to enable the installed package(s) that you + need. + + (New in 0.4a2) If this option is not directly specified on the command line + or in a distutils configuration file, the distutils default installation + location is used. Normally, this would be the ``site-packages`` directory, + but if you are using distutils configuration files, setting things like + ``prefix`` or ``install_lib``, then those settings are taken into + account when computing the default installation directory, as is the + ``--prefix`` option. + +``--script-dir=DIR, -s DIR`` + Set the script installation directory. If you don't supply this option + (via the command line or a configuration file), but you *have* supplied + an ``--install-dir`` (via command line or config file), then this option + defaults to the same directory, so that the scripts will be able to find + their associated package installation. Otherwise, this setting defaults + to the location where the distutils would normally install scripts, taking + any distutils configuration file settings into account. + +``--exclude-scripts, -x`` + Don't install scripts. This is useful if you need to install multiple + versions of a package, but do not want to reset the version that will be + run by scripts that are already installed. + +``--user`` (New in 0.6.11) + Use the user-site-packages as specified in :pep:`370` + instead of the global site-packages. + +``--always-copy, -a`` (New in 0.5a4) + Copy all needed distributions to the installation directory, even if they + are already present in a directory on sys.path. In older versions of + EasyInstall, this was the default behavior, but now you must explicitly + request it. By default, EasyInstall will no longer copy such distributions + from other sys.path directories to the installation directory, unless you + explicitly gave the distribution's filename on the command line. + + Note that as of 0.6a10, using this option excludes "system" and + "development" eggs from consideration because they can't be reliably + copied. This may cause EasyInstall to choose an older version of a package + than what you expected, or it may cause downloading and installation of a + fresh copy of something that's already installed. You will see warning + messages for any eggs that EasyInstall skips, before it falls back to an + older version or attempts to download a fresh copy. + +``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES`` + Scan the specified "download pages" or directories for direct links to eggs + or other distributions. Any existing file or directory names or direct + download URLs are immediately added to EasyInstall's search cache, and any + indirect URLs (ones that don't point to eggs or other recognized archive + formats) are added to a list of additional places to search for download + links. As soon as EasyInstall has to go online to find a package (either + because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was + used), the specified URLs will be downloaded and scanned for additional + direct links. + + Eggs and archives found by way of ``--find-links`` are only downloaded if + they are needed to meet a requirement specified on the command line; links + to unneeded packages are ignored. + + If all requested packages can be found using links on the specified + download pages, the Python Package Index will not be consulted unless you + also specified the ``--upgrade`` or ``-U`` option. + + (Note: if you want to refer to a local HTML file containing links, you must + use a ``file:`` URL, as filenames that do not refer to a directory, egg, or + archive are ignored.) + + You may specify multiple URLs or file/directory names with this option, + separated by whitespace. Note that on the command line, you will probably + have to surround the URL list with quotes, so that it is recognized as a + single option value. You can also specify URLs in a configuration file; + see `Configuration Files`_, above. + + Changed in 0.6a10: previously all URLs and directories passed to this + option were scanned as early as possible, but from 0.6a10 on, only + directories and direct archive links are scanned immediately; URLs are not + retrieved unless a package search was already going to go online due to a + package not being available locally, or due to the use of the ``--update`` + or ``-U`` option. + +``--no-find-links`` Blocks the addition of any link. + This parameter is useful if you want to avoid adding links defined in a + project easy_install is installing (whether it's a requested project or a + dependency). When used, ``--find-links`` is ignored. + + Added in Distribute 0.6.11 and Setuptools 0.7. + +``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7) + Specifies the base URL of the Python Package Index. The default is + https://pypi.org/simple/ if not specified. When a package is requested + that is not locally available or linked from a ``--find-links`` download + page, the package index will be searched for download pages for the needed + package, and those download pages will be searched for links to download + an egg or source distribution. + +``--editable, -e`` (New in 0.6a1) + Only find and download source distributions for the specified projects, + unpacking them to subdirectories of the specified ``--build-directory``. + EasyInstall will not actually build or install the requested projects or + their dependencies; it will just find and extract them for you. See + `Editing and Viewing Source Packages`_ above for more details. + +``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1) + Set the directory used to build source packages. If a package is built + from a source distribution or checkout, it will be extracted to a + subdirectory of the specified directory. The subdirectory will have the + same name as the extracted distribution's project, but in all-lowercase. + If a file or directory of that name already exists in the given directory, + a warning will be printed to the console, and the build will take place in + a temporary directory instead. + + This option is most useful in combination with the ``--editable`` option, + which forces EasyInstall to *only* find and extract (but not build and + install) source distributions. See `Editing and Viewing Source Packages`_, + above, for more information. + +``--verbose, -v, --quiet, -q`` (New in 0.4a4) + Control the level of detail of EasyInstall's progress messages. The + default detail level is "info", which prints information only about + relatively time-consuming operations like running a setup script, unpacking + an archive, or retrieving a URL. Using ``-q`` or ``--quiet`` drops the + detail level to "warn", which will only display installation reports, + warnings, and errors. Using ``-v`` or ``--verbose`` increases the detail + level to include individual file-level operations, link analysis messages, + and distutils messages from any setup scripts that get run. If you include + the ``-v`` option more than once, the second and subsequent uses are passed + down to any setup scripts, increasing the verbosity of their reporting as + well. + +``--dry-run, -n`` (New in 0.4a4) + Don't actually install the package or scripts. This option is passed down + to any setup scripts run, so packages should not actually build either. + This does *not* skip downloading, nor does it skip extracting source + distributions to a temporary/build directory. + +``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4) + If you are installing from a source distribution, and are *not* using the + ``--zip-ok`` option, this option controls the optimization level for + compiling installed ``.py`` files to ``.pyo`` files. It does not affect + the compilation of modules contained in ``.egg`` files, only those in + ``.egg`` directories. The optimization level can be set to 0, 1, or 2; + the default is 0 (unless it's set under ``install`` or ``install_lib`` in + one of your distutils configuration files). + +``--record=FILENAME`` (New in 0.5a4) + Write a record of all installed files to FILENAME. This is basically the + same as the same option for the standard distutils "install" command, and + is included for compatibility with tools that expect to pass this option + to "setup.py install". + +``--site-dirs=DIRLIST, -S DIRLIST`` (New in 0.6a1) + Specify one or more custom "site" directories (separated by commas). + "Site" directories are directories where ``.pth`` files are processed, such + as the main Python ``site-packages`` directory. As of 0.6a10, EasyInstall + automatically detects whether a given directory processes ``.pth`` files + (or can be made to do so), so you should not normally need to use this + option. It is is now only necessary if you want to override EasyInstall's + judgment and force an installation directory to be treated as if it + supported ``.pth`` files. + +``--no-deps, -N`` (New in 0.6a6) + Don't install any dependencies. This is intended as a convenience for + tools that wrap eggs in a platform-specific packaging system. (We don't + recommend that you use it for anything else.) + +``--allow-hosts=PATTERNS, -H PATTERNS`` (New in 0.6a6) + Restrict downloading and spidering to hosts matching the specified glob + patterns. E.g. ``-H *.python.org`` restricts web access so that only + packages listed and downloadable from machines in the ``python.org`` + domain. The glob patterns must match the *entire* user/host/port section of + the target URL(s). For example, ``*.python.org`` will NOT accept a URL + like ``http://python.org/foo`` or ``http://www.python.org:8080/``. + Multiple patterns can be specified by separating them with commas. The + default pattern is ``*``, which matches anything. + + In general, this option is mainly useful for blocking EasyInstall's web + access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet + or other trusted site. EasyInstall will do the best it can to satisfy + dependencies given your host restrictions, but of course can fail if it + can't find suitable packages. EasyInstall displays all blocked URLs, so + that you can adjust your ``--allow-hosts`` setting if it is more strict + than you intended. Some sites may wish to define a restrictive default + setting for this option in their `configuration files`_, and then manually + override the setting on the command line as needed. + +``--prefix=DIR`` (New in 0.6a10) + Use the specified directory as a base for computing the default + installation and script directories. On Windows, the resulting default + directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``, + while on other platforms the defaults will be + ``prefix/lib/python2.X/site-packages`` (with the appropriate version + substituted) for libraries and ``prefix/bin`` for scripts. + + Note that the ``--prefix`` option only sets the *default* installation and + script directories, and does not override the ones set on the command line + or in a configuration file. + +``--local-snapshots-ok, -l`` (New in 0.6c6) + Normally, EasyInstall prefers to only install *released* versions of + projects, not in-development ones, because such projects may not + have a currently-valid version number. So, it usually only installs them + when their ``setup.py`` directory is explicitly passed on the command line. + + However, if this option is used, then any in-development projects that were + installed using the ``setup.py develop`` command, will be used to build + eggs, effectively upgrading the "in-development" project to a snapshot + release. Normally, this option is used only in conjunction with the + ``--always-copy`` option to create a distributable snapshot of every egg + needed to run an application. + + Note that if you use this option, you must make sure that there is a valid + version number (such as an SVN revision number tag) for any in-development + projects that may be used, as otherwise EasyInstall may not be able to tell + what version of the project is "newer" when future installations or + upgrades are attempted. + + +.. _non-root installation: + +Custom Installation Locations +----------------------------- + +By default, EasyInstall installs python packages into Python's main ``site-packages`` directory, +and manages them using a custom ``.pth`` file in that same directory. + +Very often though, a user or developer wants ``easy_install`` to install and manage python packages +in an alternative location, usually for one of 3 reasons: + +1. They don't have access to write to the main Python site-packages directory. + +2. They want a user-specific stash of packages, that is not visible to other users. + +3. They want to isolate a set of packages to a specific python application, usually to minimize + the possibility of version conflicts. + +Historically, there have been many approaches to achieve custom installation. +The following section lists only the easiest and most relevant approaches [1]_. + +`Use the "--user" option`_ + +`Use the "--user" option and customize "PYTHONUSERBASE"`_ + +`Use "virtualenv"`_ + +.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_. + +.. _PEP-370: http://www.python.org/dev/peps/pep-0370/ + + +Use the "--user" option +~~~~~~~~~~~~~~~~~~~~~~~ +Python provides a User scheme for installation, which means that all +python distributions support an alternative install location that is specific to a user [3]_. +The Default location for each OS is explained in the python documentation +for the ``site.USER_BASE`` variable. This mode of installation can be turned on by +specifying the ``--user`` option to ``setup.py install`` or ``easy_install``. +This approach serves the need to have a user-specific stash of packages. + +.. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized. + +Use the "--user" option and customize "PYTHONUSERBASE" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The User scheme install location can be customized by setting the ``PYTHONUSERBASE`` environment +variable, which updates the value of ``site.USER_BASE``. To isolate packages to a specific +application, simply set the OS environment of that application to a specific value of +``PYTHONUSERBASE``, that contains just those packages. + +Use "virtualenv" +~~~~~~~~~~~~~~~~ +"virtualenv" is a 3rd-party python package that effectively "clones" a python installation, thereby +creating an isolated location to install packages. The evolution of "virtualenv" started before the existence +of the User installation scheme. "virtualenv" provides a version of ``easy_install`` that is +scoped to the cloned python install and is used in the normal way. "virtualenv" does offer various features +that the User installation scheme alone does not provide, e.g. the ability to hide the main python site-packages. + +Please refer to the :pypi:`virtualenv` documentation for more details. + + +Package Index "API" +------------------- + +Custom package indexes (and PyPI) must follow the following rules for +EasyInstall to be able to look up and download packages: + +1. Except where stated otherwise, "pages" are HTML or XHTML, and "links" + refer to ``href`` attributes. + +2. Individual project version pages' URLs must be of the form + ``base/projectname/version``, where ``base`` is the package index's base URL. + +3. Omitting the ``/version`` part of a project page's URL (but keeping the + trailing ``/``) should result in a page that is either: + + a) The single active version of that project, as though the version had been + explicitly included, OR + + b) A page with links to all of the active version pages for that project. + +4. Individual project version pages should contain direct links to downloadable + distributions where possible. It is explicitly permitted for a project's + "long_description" to include URLs, and these should be formatted as HTML + links by the package index, as EasyInstall does no special processing to + identify what parts of a page are index-specific and which are part of the + project's supplied description. + +5. Where available, MD5 information should be added to download URLs by + appending a fragment identifier of the form ``#md5=...``, where ``...`` is + the 32-character hex MD5 digest. EasyInstall will verify that the + downloaded file's MD5 digest matches the given value. + +6. Individual project version pages should identify any "homepage" or + "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes + on the HTML elements linking to those URLs. Use of these attributes will + cause EasyInstall to always follow the provided links, unless it can be + determined by inspection that they are downloadable distributions. If the + links are not to downloadable distributions, they are retrieved, and if they + are HTML, they are scanned for download links. They are *not* scanned for + additional "homepage" or "download" links, as these are only processed for + pages that are part of a package index site. + +7. The root URL of the index, if retrieved with a trailing ``/``, must result + in a page containing links to *all* projects' active version pages. + + (Note: This requirement is a workaround for the absence of case-insensitive + ``safe_name()`` matching of project names in URL paths. If project names are + matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar + mechanism), then it is not necessary to include this all-packages listing + page.) + +8. If a package index is accessed via a ``file://`` URL, then EasyInstall will + automatically use ``index.html`` files, if present, when trying to read a + directory with a trailing ``/`` on the URL. diff --git a/docs/deprecated/functionalities.rst b/docs/deprecated/functionalities.rst new file mode 100644 index 00000000..7213c5d6 --- /dev/null +++ b/docs/deprecated/functionalities.rst @@ -0,0 +1,33 @@ +"Eggsecutable" Scripts +---------------------- + +.. deprecated:: 45.3.0 + +Occasionally, there are situations where it's desirable to make an ``.egg`` +file directly executable. You can do this by including an entry point such +as the following:: + + setup( + # other arguments here... + entry_points={ + "setuptools.installation": [ + "eggsecutable = my_package.some_module:main_func", + ] + } + ) + +Any eggs built from the above setup script will include a short executable +prelude that imports and calls ``main_func()`` from ``my_package.some_module``. +The prelude can be run on Unix-like platforms (including Mac and Linux) by +invoking the egg with ``/bin/sh``, or by enabling execute permissions on the +``.egg`` file. For the executable prelude to run, the appropriate version of +Python must be available via the ``PATH`` environment variable, under its +"long" name. That is, if the egg is built for Python 2.3, there must be a +``python2.3`` executable present in a directory on ``PATH``. + +IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or +invoked via symlinks. They *must* be invoked using their original filename, in +order to ensure that, once running, ``pkg_resources`` will know what project +and version is in use. The header script will check this and exit with an +error if the ``.egg`` file has been renamed or is invoked via a symlink that +changes its base name. diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst new file mode 100644 index 00000000..0ea66cf6 --- /dev/null +++ b/docs/deprecated/index.rst @@ -0,0 +1,25 @@ +====================================================== +Guides on backward compatibility & deprecated practice +====================================================== + +``Setuptools`` has undergone tremendous changes since its first debut. As its +development continues to roll forward, many of the practice and mechanisms it +had established are now considered deprecated. But they still remain relevant +as a plethora of libraries continue to depend on them. Many people also find +it necessary to equip themselves with the knowledge to better support backward +compatibility. This guide aims to provide the essential information for such +objectives. + +.. toctree:: + :maxdepth: 1 + + changed_keywords + dependency_links + python_eggs + easy_install + zip_safe + resource_extraction + distutils/index + distutils-legacy + functionalities + commands diff --git a/docs/deprecated/python_eggs.rst b/docs/deprecated/python_eggs.rst new file mode 100644 index 00000000..59d1adc5 --- /dev/null +++ b/docs/deprecated/python_eggs.rst @@ -0,0 +1,675 @@ +===================================== +The Internal Structure of Python Eggs +===================================== + +STOP! This is not the first document you should read! + + + +---------------------- +Eggs and their Formats +---------------------- + +A "Python egg" is a logical structure embodying the release of a +specific version of a Python project, comprising its code, resources, +and metadata. There are multiple formats that can be used to physically +encode a Python egg, and others can be developed. However, a key +principle of Python eggs is that they should be discoverable and +importable. That is, it should be possible for a Python application to +easily and efficiently find out what eggs are present on a system, and +to ensure that the desired eggs' contents are importable. + +There are two basic formats currently implemented for Python eggs: + +1. ``.egg`` format: a directory or zipfile *containing* the project's + code and resources, along with an ``EGG-INFO`` subdirectory that + contains the project's metadata + +2. ``.egg-info`` format: a file or directory placed *adjacent* to the + project's code and resources, that directly contains the project's + metadata. + +Both formats can include arbitrary Python code and resources, including +static data files, package and non-package directories, Python +modules, C extension modules, and so on. But each format is optimized +for different purposes. + +The ``.egg`` format is well-suited to distribution and the easy +uninstallation or upgrades of code, since the project is essentially +self-contained within a single directory or file, unmingled with any +other projects' code or resources. It also makes it possible to have +multiple versions of a project simultaneously installed, such that +individual programs can select the versions they wish to use. + +The ``.egg-info`` format, on the other hand, was created to support +backward-compatibility, performance, and ease of installation for system +packaging tools that expect to install all projects' code and resources +to a single directory (e.g. ``site-packages``). Placing the metadata +in that same directory simplifies the installation process, since it +isn't necessary to create ``.pth`` files or otherwise modify +``sys.path`` to include each installed egg. + +Its disadvantage, however, is that it provides no support for clean +uninstallation or upgrades, and of course only a single version of a +project can be installed to a given directory. Thus, support from a +package management tool is required. (This is why setuptools' "install" +command refers to this type of egg installation as "single-version, +externally managed".) Also, they lack sufficient data to allow them to +be copied from their installation source. easy_install can "ship" an +application by copying ``.egg`` files or directories to a target +location, but it cannot do this for ``.egg-info`` installs, because +there is no way to tell what code and resources belong to a particular +egg -- there may be several eggs "scrambled" together in a single +installation location, and the ``.egg-info`` format does not currently +include a way to list the files that were installed. (This may change +in a future version.) + + +Code and Resources +================== + +The layout of the code and resources is dictated by Python's normal +import layout, relative to the egg's "base location". + +For the ``.egg`` format, the base location is the ``.egg`` itself. That +is, adding the ``.egg`` filename or directory name to ``sys.path`` +makes its contents importable. + +For the ``.egg-info`` format, however, the base location is the +directory that *contains* the ``.egg-info``, and thus it is the +directory that must be added to ``sys.path`` to make the egg importable. +(Note that this means that the "normal" installation of a package to a +``sys.path`` directory is sufficient to make it an "egg" if it has an +``.egg-info`` file or directory installed alongside of it.) + + +Project Metadata +================= + +If eggs contained only code and resources, there would of course be +no difference between them and any other directory or zip file on +``sys.path``. Thus, metadata must also be included, using a metadata +file or directory. + +For the ``.egg`` format, the metadata is placed in an ``EGG-INFO`` +subdirectory, directly within the ``.egg`` file or directory. For the +``.egg-info`` format, metadata is stored directly within the +``.egg-info`` directory itself. + +The minimum project metadata that all eggs must have is a standard +Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the +metadata directory appropriate to the format. Because it's possible for +this to be the only metadata file included, ``.egg-info`` format eggs +are not required to be a directory; they can just be a ``.egg-info`` +file that directly contains the ``PKG-INFO`` metadata. This eliminates +the need to create a directory just to store one file. This option is +*not* available for ``.egg`` formats, since setuptools always includes +other metadata. (In fact, setuptools itself never generates +``.egg-info`` files, either; the support for using files was added so +that the requirement could easily be satisfied by other tools, such +as distutils). + +In addition to the ``PKG-INFO`` file, an egg's metadata directory may +also include files and directories representing various forms of +optional standard metadata (see the section on `Standard Metadata`_, +below) or user-defined metadata required by the project. For example, +some projects may define a metadata format to describe their application +plugins, and metadata in this format would then be included by plugin +creators in their projects' metadata directories. + + +Filename-Embedded Metadata +========================== + +To allow introspection of installed projects and runtime resolution of +inter-project dependencies, a certain amount of information is embedded +in egg filenames. At a minimum, this includes the project name, and +ideally will also include the project version number. Optionally, it +can also include the target Python version and required runtime +platform if platform-specific C code is included. The syntax of an +egg filename is as follows:: + + name ["-" version ["-py" pyver ["-" required_platform]]] "." ext + +The "name" and "version" should be escaped using the ``to_filename()`` +function provided by ``pkg_resources``, after first processing them with +``safe_name()`` and ``safe_version()`` respectively. These latter two +functions can also be used to later "unescape" these parts of the +filename. (For a detailed description of these transformations, please +see the "Parsing Utilities" section of the ``pkg_resources`` manual.) + +The "pyver" string is the Python major version, as found in the first +3 characters of ``sys.version``. "required_platform" is essentially +a distutils ``get_platform()`` string, but with enhancements to properly +distinguish Mac OS versions. (See the ``get_build_platform()`` +documentation in the "Platform Utilities" section of the +``pkg_resources`` manual for more details.) + +Finally, the "ext" is either ``.egg`` or ``.egg-info``, as appropriate +for the egg's format. + +Normally, an egg's filename should include at least the project name and +version, as this allows the runtime system to find desired project +versions without having to read the egg's PKG-INFO to determine its +version number. + +Setuptools, however, only includes the version number in the filename +when an ``.egg`` file is built using the ``bdist_egg`` command, or when +an ``.egg-info`` directory is being installed by the +``install_egg_info`` command. When generating metadata for use with the +original source tree, it only includes the project name, so that the +directory will not have to be renamed each time the project's version +changes. + +This is especially important when version numbers change frequently, and +the source metadata directory is kept under version control with the +rest of the project. (As would be the case when the project's source +includes project-defined metadata that is not generated from by +setuptools from data in the setup script.) + + +Egg Links +========= + +In addition to the ``.egg`` and ``.egg-info`` formats, there is a third +egg-related extension that you may encounter on occasion: ``.egg-link`` +files. + +These files are not eggs, strictly speaking. They simply provide a way +to reference an egg that is not physically installed in the desired +location. They exist primarily as a cross-platform alternative to +symbolic links, to support "installing" code that is being developed in +a different location than the desired installation location. For +example, if a user is developing an application plugin in their home +directory, but the plugin needs to be "installed" in an application +plugin directory, running "setup.py develop -md /path/to/app/plugins" +will install an ``.egg-link`` file in ``/path/to/app/plugins``, that +tells the egg runtime system where to find the actual egg (the user's +project source directory and its ``.egg-info`` subdirectory). + +``.egg-link`` files are named following the format for ``.egg`` and +``.egg-info`` names, but only the project name is included; no version, +Python version, or platform information is included. When the runtime +searches for available eggs, ``.egg-link`` files are opened and the +actual egg file/directory name is read from them. + +Each ``.egg-link`` file should contain a single file or directory name, +with no newlines. This filename should be the base location of one or +more eggs. That is, the name must either end in ``.egg``, or else it +should be the parent directory of one or more ``.egg-info`` format eggs. + +As of setuptools 0.6c6, the path may be specified as a platform-independent +(i.e. ``/``-separated) relative path from the directory containing the +``.egg-link`` file, and a second line may appear in the file, specifying a +platform-independent relative path from the egg's base directory to its +setup script directory. This allows installation tools such as EasyInstall +to find the project's setup directory and build eggs or perform other setup +commands on it. + + +----------------- +Standard Metadata +----------------- + +In addition to the minimum required ``PKG-INFO`` metadata, projects can +include a variety of standard metadata files or directories, as +described below. Except as otherwise noted, these files and directories +are automatically generated by setuptools, based on information supplied +in the setup script or through analysis of the project's code and +resources. + +Most of these files and directories are generated via "egg-info +writers" during execution of the setuptools ``egg_info`` command, and +are listed in the ``egg_info.writers`` entry point group defined by +setuptools' own ``setup.py`` file. + +Project authors can register their own metadata writers as entry points +in this group (as described in the setuptools manual under "Adding new +EGG-INFO Files") to cause setuptools to generate project-specific +metadata files or directories during execution of the ``egg_info`` +command. It is up to project authors to document these new metadata +formats, if they create any. + + +``.txt`` File Formats +===================== + +Files described in this section that have ``.txt`` extensions have a +simple lexical format consisting of a sequence of text lines, each line +terminated by a linefeed character (regardless of platform). Leading +and trailing whitespace on each line is ignored, as are blank lines and +lines whose first nonblank character is a ``#`` (comment symbol). (This +is the parsing format defined by the ``yield_lines()`` function of +the ``pkg_resources`` module.) + +All ``.txt`` files defined by this section follow this format, but some +are also "sectioned" files, meaning that their contents are divided into +sections, using square-bracketed section headers akin to Windows +``.ini`` format. Note that this does *not* imply that the lines within +the sections follow an ``.ini`` format, however. Please see an +individual metadata file's documentation for a description of what the +lines and section names mean in that particular file. + +Sectioned files can be parsed using the ``split_sections()`` function; +see the "Parsing Utilities" section of the ``pkg_resources`` manual for +for details. + + +Dependency Metadata +=================== + + +``requires.txt`` +---------------- + +This is a "sectioned" text file. Each section is a sequence of +"requirements", as parsed by the ``parse_requirements()`` function; +please see the ``pkg_resources`` manual for the complete requirement +parsing syntax. + +The first, unnamed section (i.e., before the first section header) in +this file is the project's core requirements, which must be installed +for the project to function. (Specified using the ``install_requires`` +keyword to ``setup()``). + +The remaining (named) sections describe the project's "extra" +requirements, as specified using the ``extras_require`` keyword to +``setup()``. The section name is the name of the optional feature, and +the section body lists that feature's dependencies. + +Note that it is not normally necessary to inspect this file directly; +``pkg_resources.Distribution`` objects have a ``requires()`` method +that can be used to obtain ``Requirement`` objects describing the +project's core and optional dependencies. + + +``setup_requires.txt`` +---------------------- + +Much like ``requires.txt`` except represents the requirements +specified by the ``setup_requires`` parameter to the Distribution. + + +``dependency_links.txt`` +------------------------ + +A list of dependency URLs, one per line, as specified using the +``dependency_links`` keyword to ``setup()``. These may be direct +download URLs, or the URLs of web pages containing direct download +links. Please see the setuptools manual for more information on +specifying this option. + + +``depends.txt`` -- Obsolete, do not create! +------------------------------------------- + +This file follows an identical format to ``requires.txt``, but is +obsolete and should not be used. The earliest versions of setuptools +required users to manually create and maintain this file, so the runtime +still supports reading it, if it exists. The new filename was created +so that it could be automatically generated from ``setup()`` information +without overwriting an existing hand-created ``depends.txt``, if one +was already present in the project's source ``.egg-info`` directory. + + +``namespace_packages.txt`` -- Namespace Package Metadata +======================================================== + +A list of namespace package names, one per line, as supplied to the +``namespace_packages`` keyword to ``setup()``. Please see the manuals +for setuptools and ``pkg_resources`` for more information about +namespace packages. + + +``entry_points.txt`` -- "Entry Point"/Plugin Metadata +===================================================== + +This is a "sectioned" text file, whose contents encode the +``entry_points`` keyword supplied to ``setup()``. All sections are +named, as the section names specify the entry point groups in which the +corresponding section's entry points are registered. + +Each section is a sequence of "entry point" lines, each parseable using +the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources`` +manual for the complete entry point parsing syntax. + +Note that it is not necessary to parse this file directly; the +``pkg_resources`` module provides a variety of APIs to locate and load +entry points automatically. Please see the setuptools and +``pkg_resources`` manuals for details on the nature and uses of entry +points. + + +The ``scripts`` Subdirectory +============================ + +This directory is currently only created for ``.egg`` files built by +the setuptools ``bdist_egg`` command. It will contain copies of all +of the project's "traditional" scripts (i.e., those specified using the +``scripts`` keyword to ``setup()``). This is so that they can be +reconstituted when an ``.egg`` file is installed. + +The scripts are placed here using the distutils' standard +``install_scripts`` command, so any ``#!`` lines reflect the Python +installation where the egg was built. But instead of copying the +scripts to the local script installation directory, EasyInstall writes +short wrapper scripts that invoke the original scripts from inside the +egg, after ensuring that sys.path includes the egg and any eggs it +depends on. For more about `script wrappers`_, see the section below on +`Installation and Path Management Issues`_. + + +Zip Support Metadata +==================== + + +``native_libs.txt`` +------------------- + +A list of C extensions and other dynamic link libraries contained in +the egg, one per line. Paths are ``/``-separated and relative to the +egg's base location. + +This file is generated as part of ``bdist_egg`` processing, and as such +only appears in ``.egg`` files (and ``.egg`` directories created by +unpacking them). It is used to ensure that all libraries are extracted +from a zipped egg at the same time, in case there is any direct linkage +between them. Please see the `Zip File Issues`_ section below for more +information on library and resource extraction from ``.egg`` files. + + +``eager_resources.txt`` +----------------------- + +A list of resource files and/or directories, one per line, as specified +via the ``eager_resources`` keyword to ``setup()``. Paths are +``/``-separated and relative to the egg's base location. + +Resource files or directories listed here will be extracted +simultaneously, if any of the named resources are extracted, or if any +native libraries listed in ``native_libs.txt`` are extracted. Please +see the setuptools manual for details on what this feature is used for +and how it works, as well as the `Zip File Issues`_ section below. + + +``zip-safe`` and ``not-zip-safe`` +--------------------------------- + +These are zero-length files, and either one or the other should exist. +If ``zip-safe`` exists, it means that the project will work properly +when installed as an ``.egg`` zipfile, and conversely the existence of +``not-zip-safe`` means the project should not be installed as an +``.egg`` file. The ``zip_safe`` option to setuptools' ``setup()`` +determines which file will be written. If the option isn't provided, +setuptools attempts to make its own assessment of whether the package +can work, based on code and content analysis. + +If neither file is present at installation time, EasyInstall defaults +to assuming that the project should be unzipped. (Command-line options +to EasyInstall, however, take precedence even over an existing +``zip-safe`` or ``not-zip-safe`` file.) + +Note that these flag files appear only in ``.egg`` files generated by +``bdist_egg``, and in ``.egg`` directories created by unpacking such an +``.egg`` file. + + + +``top_level.txt`` -- Conflict Management Metadata +================================================= + +This file is a list of the top-level module or package names provided +by the project, one Python identifier per line. + +Subpackages are not included; a project containing both a ``foo.bar`` +and a ``foo.baz`` would include only one line, ``foo``, in its +``top_level.txt``. + +This data is used by ``pkg_resources`` at runtime to issue a warning if +an egg is added to ``sys.path`` when its contained packages may have +already been imported. + +(It was also once used to detect conflicts with non-egg packages at +installation time, but in more recent versions, setuptools installs eggs +in such a way that they always override non-egg packages, thus +preventing a problem from arising.) + + +``SOURCES.txt`` -- Source Files Manifest +======================================== + +This file is roughly equivalent to the distutils' ``MANIFEST`` file. +The differences are as follows: + +* The filenames always use ``/`` as a path separator, which must be + converted back to a platform-specific path whenever they are read. + +* The file is automatically generated by setuptools whenever the + ``egg_info`` or ``sdist`` commands are run, and it is *not* + user-editable. + +Although this metadata is included with distributed eggs, it is not +actually used at runtime for any purpose. Its function is to ensure +that setuptools-built *source* distributions can correctly discover +what files are part of the project's source, even if the list had been +generated using revision control metadata on the original author's +system. + +In other words, ``SOURCES.txt`` has little or no runtime value for being +included in distributed eggs, and it is possible that future versions of +the ``bdist_egg`` and ``install_egg_info`` commands will strip it before +installation or distribution. Therefore, do not rely on its being +available outside of an original source directory or source +distribution. + + +------------------------------ +Other Technical Considerations +------------------------------ + + +Zip File Issues +=============== + +Although zip files resemble directories, they are not fully +substitutable for them. Most platforms do not support loading dynamic +link libraries contained in zipfiles, so it is not possible to directly +import C extensions from ``.egg`` zipfiles. Similarly, there are many +existing libraries -- whether in Python or C -- that require actual +operating system filenames, and do not work with arbitrary "file-like" +objects or in-memory strings, and thus cannot operate directly on the +contents of zip files. + +To address these issues, the ``pkg_resources`` module provides a +"resource API" to support obtaining either the contents of a resource, +or a true operating system filename for the resource. If the egg +containing the resource is a directory, the resource's real filename +is simply returned. However, if the egg is a zipfile, then the +resource is first extracted to a cache directory, and the filename +within the cache is returned. + +The cache directory is determined by the ``pkg_resources`` API; please +see the ``set_cache_path()`` and ``get_default_cache()`` documentation +for details. + + +The Extraction Process +---------------------- + +Resources are extracted to a cache subdirectory whose name is based +on the enclosing ``.egg`` filename and the path to the resource. If +there is already a file of the correct name, size, and timestamp, its +filename is returned to the requester. Otherwise, the desired file is +extracted first to a temporary name generated using +``mkstemp(".$extract",target_dir)``, and then its timestamp is set to +match the one in the zip file, before renaming it to its final name. +(Some collision detection and resolution code is used to handle the +fact that Windows doesn't overwrite files when renaming.) + +If a resource directory is requested, all of its contents are +recursively extracted in this fashion, to ensure that the directory +name can be used as if it were valid all along. + +If the resource requested for extraction is listed in the +``native_libs.txt`` or ``eager_resources.txt`` metadata files, then +*all* resources listed in *either* file will be extracted before the +requested resource's filename is returned, thus ensuring that all +C extensions and data used by them will be simultaneously available. + + +Extension Import Wrappers +------------------------- + +Since Python's built-in zip import feature does not support loading +C extension modules from zipfiles, the setuptools ``bdist_egg`` command +generates special import wrappers to make it work. + +The wrappers are ``.py`` files (along with corresponding ``.pyc`` +and/or ``.pyo`` files) that have the same module name as the +corresponding C extension. These wrappers are located in the same +package directory (or top-level directory) within the zipfile, so that +say, ``foomodule.so`` will get a corresponding ``foo.py``, while +``bar/baz.pyd`` will get a corresponding ``bar/baz.py``. + +These wrapper files contain a short stanza of Python code that asks +``pkg_resources`` for the filename of the corresponding C extension, +then reloads the module using the obtained filename. This will cause +``pkg_resources`` to first ensure that all of the egg's C extensions +(and any accompanying "eager resources") are extracted to the cache +before attempting to link to the C library. + +Note, by the way, that ``.egg`` directories will also contain these +wrapper files. However, Python's default import priority is such that +C extensions take precedence over same-named Python modules, so the +import wrappers are ignored unless the egg is a zipfile. + + +Installation and Path Management Issues +======================================= + +Python's initial setup of ``sys.path`` is very dependent on the Python +version and installation platform, as well as how Python was started +(i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter). +In fact, Python also provides only two relatively robust ways to affect +``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH`` +environment variable, and ``.pth`` files. + +However, with no cross-platform way to safely and persistently change +environment variables, this leaves ``.pth`` files as EasyInstall's only +real option for persistent configuration of ``sys.path``. + +But ``.pth`` files are rather strictly limited in what they are allowed +to do normally. They add directories only to the *end* of ``sys.path``, +after any locally-installed ``site-packages`` directory, and they are +only processed *in* the ``site-packages`` directory to start with. + +This is a double whammy for users who lack write access to that +directory, because they can't create a ``.pth`` file that Python will +read, and even if a sympathetic system administrator adds one for them +that calls ``site.addsitedir()`` to allow some other directory to +contain ``.pth`` files, they won't be able to install newer versions of +anything that's installed in the systemwide ``site-packages``, because +their paths will still be added *after* ``site-packages``. + +So EasyInstall applies two workarounds to solve these problems. + +The first is that EasyInstall leverages ``.pth`` files' "import" feature +to manipulate ``sys.path`` and ensure that anything EasyInstall adds +to a ``.pth`` file will always appear before both the standard library +and the local ``site-packages`` directories. Thus, it is always +possible for a user who can write a Python-read ``.pth`` file to ensure +that their packages come first in their own environment. + +Second, when installing to a ``PYTHONPATH`` directory (as opposed to +a "site" directory like ``site-packages``) EasyInstall will also install +a special version of the ``site`` module. Because it's in a +``PYTHONPATH`` directory, this module will get control before the +standard library version of ``site`` does. It will record the state of +``sys.path`` before invoking the "real" ``site`` module, and then +afterwards it processes any ``.pth`` files found in ``PYTHONPATH`` +directories, including all the fixups needed to ensure that eggs always +appear before the standard library in sys.path, but are in a relative +order to one another that is defined by their ``PYTHONPATH`` and +``.pth``-prescribed sequence. + +The net result of these changes is that ``sys.path`` order will be +as follows at runtime: + +1. The ``sys.argv[0]`` directory, or an empty string if no script + is being executed. + +2. All eggs installed by EasyInstall in any ``.pth`` file in each + ``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order, + then normal ``.pth`` processing order (which is to say alphabetical + by ``.pth`` filename, then by the order of listing within each + ``.pth`` file). + +3. All eggs installed by EasyInstall in any ``.pth`` file in each "site" + directory (such as ``site-packages``), following the same ordering + rules as for the ones on ``PYTHONPATH``. + +4. The ``PYTHONPATH`` directories themselves, in their original order + +5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not* + eggs installed by EasyInstall, again following the same relative + ordering rules. + +6. The standard library and "site" directories, along with the contents + of any ``.pth`` files found in the "site" directories. + +Notice that sections 1, 4, and 6 comprise the "normal" Python setup for +``sys.path``. Sections 2 and 3 are inserted to support eggs, and +section 5 emulates what the "normal" semantics of ``.pth`` files on +``PYTHONPATH`` would be if Python natively supported them. + +For further discussion of the tradeoffs that went into this design, as +well as notes on the actual magic inserted into ``.pth`` files to make +them do these things, please see also the following messages to the +distutils-SIG mailing list: + +* http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html +* http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html + + +Script Wrappers +--------------- + +EasyInstall never directly installs a project's original scripts to +a script installation directory. Instead, it writes short wrapper +scripts that first ensure that the project's dependencies are active +on sys.path, before invoking the original script. These wrappers +have a #! line that points to the version of Python that was used to +install them, and their second line is always a comment that indicates +the type of script wrapper, the project version required for the script +to run, and information identifying the script to be invoked. + +The format of this marker line is:: + + "# EASY-INSTALL-" script_type ": " tuple_of_strings "\n" + +The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or +``ENTRY-SCRIPT``. The ``tuple_of_strings`` is a comma-separated +sequence of Python string constants. For ``SCRIPT`` and ``DEV-SCRIPT`` +wrappers, there are two strings: the project version requirement, and +the script name (as a filename within the ``scripts`` metadata +directory). For ``ENTRY-SCRIPT`` wrappers, there are three: +the project version requirement, the entry point group name, and the +entry point name. (See the "Automatic Script Creation" section in the +setuptools manual for more information about entry point scripts.) + +In each case, the project version requirement string will be a string +parseable with the ``pkg_resources`` modules' ``Requirement.parse()`` +classmethod. The only difference between a ``SCRIPT`` wrapper and a +``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original +source script in the project's source tree, and is created when the +"setup.py develop" command is run. A ``SCRIPT`` wrapper, on the other +hand, uses the "installed" script written to the ``EGG-INFO/scripts`` +subdirectory of the corresponding ``.egg`` zipfile or directory. +(``.egg-info`` eggs do not have script wrappers associated with them, +except in the "setup.py develop" case.) + +The purpose of including the marker line in generated script wrappers is +to facilitate introspection of installed scripts, and their relationship +to installed eggs. For example, an uninstallation tool could use this +data to identify what scripts can safely be removed, and/or identify +what scripts would stop working if a particular egg is uninstalled. diff --git a/docs/deprecated/resource_extraction.rst b/docs/deprecated/resource_extraction.rst new file mode 100644 index 00000000..c481e339 --- /dev/null +++ b/docs/deprecated/resource_extraction.rst @@ -0,0 +1,54 @@ +.. _Automatic Resource Extraction: + +Automatic Resource Extraction +============================= + +In a modern setup, Python packages are usually installed as directories, +and all the files can be found on deterministic locations on the disk. +This means that most of the tools expect package resources to be "real" files. + +There are a few occasions however that packages are loaded in a different way +(e.g., from a zip file), which is incompatible with the assumptions mentioned above. +Moreover, a package developer may also include non-extension native libraries or other files that +C extensions may expect to be able to access. + +In these scenarios, the use of :mod:`importlib.resources` is recommended. + +Old implementations (prior to the advent of :mod:`importlib.resources`) and +long-living projects, however, may still rely on the library ``pkg_resources`` +to access these files. + +If you have to support such systems, or want to provide backward compatibility +for ``pkg_resources``, you may need to add an special configuration +to ``setuptools`` when packaging a project. +This can be done by listing as ``eager_resources`` (argument to ``setup()`` +in ``setup.py`` or field in ``setup.cfg``) all the files that need to be +extracted together, whenever a C extension in the project is imported. + +This is especially important if your project includes shared libraries *other* +than ``distutils``/``setuptools``-built C extensions, and those shared libraries use file +extensions other than ``.dll``, ``.so``, or ``.dylib``, which are the +extensions that setuptools 0.6a8 and higher automatically detects as shared +libraries and adds to the ``native_libs.txt`` file for you. Any shared +libraries whose names do not end with one of those extensions should be listed +as ``eager_resources``, because they need to be present in the filesystem when +he C extensions that link to them are used. + +The ``pkg_resources`` runtime for compressed packages will automatically +extract *all* C extensions and ``eager_resources`` at the same time, whenever +*any* C extension or eager resource is requested via the ``resource_filename()`` +API. (C extensions are imported using ``resource_filename()`` internally.) +This ensures that C extensions will see all of the "real" files that they +expect to see. + +Note also that you can list directory resource names in ``eager_resources`` as +well, in which case the directory's contents (including subdirectories) will be +extracted whenever any C extension or eager resource is requested. + +Please note that if you're not sure whether you need to use this argument, you +don't! It's really intended to support projects with lots of non-Python +dependencies and as a last resort for crufty projects that can't otherwise +handle being compressed. If your package is pure Python, Python plus data +files, or Python plus C, you really don't need this. You've got to be using +either C or an external program that needs "real" files in your project before +there's any possibility of ``eager_resources`` being relevant to your project. diff --git a/docs/deprecated/zip_safe.rst b/docs/deprecated/zip_safe.rst new file mode 100644 index 00000000..26b45662 --- /dev/null +++ b/docs/deprecated/zip_safe.rst @@ -0,0 +1,74 @@ +Understanding the ``zip_safe`` flag +=================================== + +The ``zip_safe`` flag is a ``setuptools`` configuration mainly associated +with the ``egg`` distribution format +(which got replaced in the ecosystem by the newer ``wheel`` format) and the +``easy_install`` command (deprecated in ``setuptools`` v58.3.0). + +It is very unlikely that the values of ``zip_safe`` will affect modern +deployments that use :pypi:`pip` for installing packages. +Moreover, new users of ``setuptools`` should not attempt to create egg files +using the deprecated ``build_egg`` command. +Therefore, this flag is considered **obsolete**. + +This document, however, describes what was the historical motivation behind +this flag, and how it was used. + +Historical Motivation +--------------------- + +For some use cases (such as bundling as part of a larger application), Python +packages may be run directly from a zip file. +Not all packages, however, are capable of running in compressed form, because +they may expect to be able to access either source code or data files as +normal operating system files. + +In the past, ``setuptools`` would install a project distributed +as a zipfile or a directory (via the ``easy_install`` command or +``python setup.py install``), +the default choice being determined by the project's ``zip_safe`` flag. + +How the ``zip_safe`` flag was used? +----------------------------------- + +To set this flag, a developer would pass a boolean value for the ``zip_safe`` argument to the +``setup()`` function, or omit it. When omitted, the ``bdist_egg`` +command would analyze the project's contents to see if it could detect any +conditions that preventing the project from working in a zipfile. + +This was extremely conservative: ``bdist_egg`` would consider the +project unsafe if it contained any C extensions or datafiles whatsoever. This +does *not* mean that the project couldn't or wouldn't work as a zipfile! It just +means that the ``bdist_egg`` authors were not yet comfortable asserting that +the project *would* work. If the project did not contain any C or data files, and did not +attempt to perform ``__file__`` or ``__path__`` introspection or source code manipulation, then +there was an extremely solid chance the project will work when installed as a +zipfile. (And if the project used ``pkg_resources`` for all its data file +access, then C extensions and other data files shouldn't be a problem at all. +See the :ref:`Accessing Data Files at Runtime` section for more information.) + +The developer could manually set ``zip_safe`` to ``True`` to perform tests, +or to override the default behaviour (after checking all the warnings and +understanding the implications), this would allow ``setuptools`` to install the +project as a zip file. Alternatively, by setting ``zip_safe`` to ``False``, +developers could force ``setuptools`` to always install the project as a +directory. + +Modern ways of loading packages from zip files +---------------------------------------------- + +Currently, popular Python package installers (such as :pypi:`pip`) and package +indexes (such as PyPI_) consider that distribution packages are always +installed as a directory. +It is however still possible to load packages from zip files added to +:obj:`sys.path`, thanks to the :mod:`zipimport` module +and the :mod:`importlib` machinery provided by Python standard library. + +When working with modules loaded from a zip file, it is important to keep in +mind that values of ``__file__`` and ``__path__`` might not work as expected. +Please check the documentation for :mod:`importlib.resources`, if file +locations are important for your use case. + + +.. _PyPI: https://pypi.org diff --git a/docs/development/developer-guide.rst b/docs/development/developer-guide.rst new file mode 100644 index 00000000..d2cf1592 --- /dev/null +++ b/docs/development/developer-guide.rst @@ -0,0 +1,133 @@ +================================ +Developer's Guide for Setuptools +================================ + +If you want to know more about contributing on Setuptools, this is the place. + + +------------------- +Recommended Reading +------------------- + +Please read `How to write the perfect pull request +<https://blog.jaraco.com/how-to-write-perfect-pull-request/>`_ for some tips +on contributing to open source projects. Although the article is not +authoritative, it was authored by the maintainer of Setuptools, so reflects +his opinions and will improve the likelihood of acceptance and quality of +contribution. + +------------------ +Project Management +------------------ + +Setuptools is maintained primarily in GitHub at `this home +<https://github.com/pypa/setuptools>`_. Setuptools is maintained under the +Python Packaging Authority (PyPA) with several core contributors. All bugs +for Setuptools are filed and the canonical source is maintained in GitHub. + +User support and discussions are done through +`GitHub Discussions <https://github.com/pypa/setuptools/discussions>`_, +or the issue tracker (for specific issues). + +Discussions about development happen on GitHub Discussions or +the ``setuptools`` channel on `PyPA Discord <https://discord.com/invite/pypa>`_. + +----------------- +Authoring Tickets +----------------- + +Before authoring any source code, it's often prudent to file a ticket +describing the motivation behind making changes. First search to see if a +ticket already exists for your issue. If not, create one. Try to think from +the perspective of the reader. Explain what behavior you expected, what you +got instead, and what factors might have contributed to the unexpected +behavior. In GitHub, surround a block of code or traceback with the triple +backtick "\`\`\`" so that it is formatted nicely. + +Filing a ticket provides a forum for justification, discussion, and +clarification. The ticket provides a record of the purpose for the change and +any hard decisions that were made. It provides a single place for others to +reference when trying to understand why the software operates the way it does +or why certain changes were made. + +Setuptools makes extensive use of hyperlinks to tickets in the changelog so +that system integrators and other users can get a quick summary, but then +jump to the in-depth discussion about any subject referenced. + +--------------------- +Making a pull request +--------------------- + +When making a pull request, please +:ref:`include a short summary of the changes <Adding change notes +with your PRs>` and a reference to any issue tickets that the PR is +intended to solve. +All PRs with code changes should include tests. All changes should +include a changelog entry. + +.. include:: ../../changelog.d/README.rst + +------------------- +Auto-Merge Requests +------------------- + +To support running all code through CI, even lightweight contributions, +the project employs Mergify to auto-merge pull requests tagged as +auto-merge. + +Use ``hub pull-request -l auto-merge`` to create such a pull request +from the command line after pushing a new branch. + +------- +Testing +------- + +The primary tests are run using tox. Make sure you have tox installed, +and invoke it:: + + $ tox + +Under continuous integration, additional tests may be run. See the +``.travis.yml`` file for full details on the tests run under Travis-CI. + +------------------- +Semantic Versioning +------------------- + +Setuptools follows ``semver``. + +.. explain value of reflecting meaning in versions. + +---------------------- +Building Documentation +---------------------- + +Setuptools relies on the `Sphinx`_ system for building documentation. +The `published documentation`_ is hosted on Read the Docs. + +To build the docs locally, use tox:: + + $ tox -e docs + +.. _Sphinx: http://www.sphinx-doc.org/en/master/ +.. _published documentation: https://setuptools.pypa.io/en/latest/ + +--------------------- +Vendored Dependencies +--------------------- + +Setuptools has some dependencies, but due to `bootstrapping issues +<https://github.com/pypa/setuptools/issues/980>`_, those dependencies +cannot be declared as they won't be resolved soon enough to build +setuptools from source. Eventually, this limitation may be lifted as +PEP 517/518 reach ubiquitous adoption, but for now, Setuptools +cannot declare dependencies other than through +``setuptools/_vendor/vendored.txt`` and +``pkg_resources/_vendor/vendored.txt``. + +All the dependencies specified in these files are "vendorized" using a +simple Python script ``tools/vendor.py``. + +To refresh the dependencies, run the following command:: + + $ tox -e vendor diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 00000000..7ee52361 --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,34 @@ +------------------------- +Development on Setuptools +------------------------- + +Setuptools is maintained by the Python community under the Python Packaging +Authority (PyPA) and led by Jason R. Coombs. + +This document describes the process by which Setuptools is developed. +This document assumes the reader has some passing familiarity with +*using* setuptools, the ``pkg_resources`` module, and pip. It +does not attempt to explain basic concepts like inter-project +dependencies, nor does it contain detailed lexical syntax for most +file formats. Neither does it explain concepts like "namespace +packages" or "resources" in any detail, as all of these subjects are +covered at length in the setuptools developer's guide and the +``pkg_resources`` reference manual. + +Instead, this is **internal** documentation for how those concepts and +features are *implemented* in concrete terms. It is intended for people +who are working on the setuptools code base, who want to be able to +troubleshoot setuptools problems, want to write code that reads the file +formats involved, or want to otherwise tinker with setuptools-generated +files and directories. + +Note, however, that these are all internal implementation details and +are therefore subject to change; stick to the published API if you don't +want to be responsible for keeping your code from breaking when +setuptools changes. You have been warned. + +.. toctree:: + :maxdepth: 1 + + developer-guide + releases diff --git a/docs/development/releases.rst b/docs/development/releases.rst new file mode 100644 index 00000000..35b415c2 --- /dev/null +++ b/docs/development/releases.rst @@ -0,0 +1,37 @@ +=============== +Release Process +=============== + +In order to allow for rapid, predictable releases, Setuptools uses a +mechanical technique for releases, enacted on tagged commits by +continuous integration. + +To finalize a release, run ``tox -e finalize``, review, then push +the changes. + +If tests pass, the release will be uploaded to PyPI. + +Release Frequency +----------------- + +Some have asked why Setuptools is released so frequently. Because Setuptools +uses a mechanical release process, it's very easy to make releases whenever the +code is stable (tests are passing). As a result, the philosophy is to release +early and often. + +While some find the frequent releases somewhat surprising, they only empower +the user. Although releases are made frequently, users can choose the frequency +at which they use those releases. If instead Setuptools contributions were only +released in batches, the user would be constrained to only use Setuptools when +those official releases were made. With frequent releases, the user can govern +exactly how often he wishes to update. + +Frequent releases also then obviate the need for dev or beta releases in most +cases. Because releases are made early and often, bugs are discovered and +corrected quickly, in many cases before other users have yet to encounter them. + +Release Managers +---------------- + +Additionally, anyone with push access to the master branch has access to cut +releases. diff --git a/docs/history.rst b/docs/history.rst index 8e217503..ce7e77ab 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -5,4 +5,43 @@ History ******* +.. towncrier-draft-entries:: DRAFT, unreleased as on |today| + .. include:: ../CHANGES (links).rst + +Credits +******* + +* The original design for the ``.egg`` format and the ``pkg_resources`` API was + co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first + version of ``pkg_resources``, and supplied the macOS operating system version + compatibility algorithm. + +* Ian Bicking implemented many early "creature comfort" features of + easy_install, including support for downloading via Sourceforge and + Subversion repositories. Ian's comments on the Web-SIG about WSGI + application deployment also inspired the concept of "entry points" in eggs, + and he has given talks at PyCon and elsewhere to inform and educate the + community about eggs and setuptools. + +* Jim Fulton contributed time and effort to build automated tests of various + aspects of ``easy_install``, and supplied the doctests for the command-line + ``.exe`` wrappers on Windows. + +* Phillip J. Eby is the seminal author of setuptools, and + first proposed the idea of an importable binary distribution format for + Python application plug-ins. + +* Significant parts of the implementation of setuptools were funded by the Open + Source Applications Foundation, to provide a plug-in infrastructure for the + Chandler PIM application. In addition, many OSAF staffers (such as Mike + "Code Bear" Taylor) contributed their time and stress as guinea pigs for the + use of eggs and setuptools, even before eggs were "cool". (Thanks, guys!) + +* Tarek Ziadé is the principal author of the Distribute fork, which + re-invigorated the community on the project, encouraged renewed innovation, + and addressed many defects. + +* Jason R. Coombs performed the merge with Distribute, maintaining the + project for several years in coordination with the Python Packaging + Authority (PyPA). diff --git a/docs/images/banner-640x320.svg b/docs/images/banner-640x320.svg new file mode 100644 index 00000000..4e908ea1 --- /dev/null +++ b/docs/images/banner-640x320.svg @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="640" height="320" version="1.1" viewBox="0 0 169.33 84.667" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <g id="g848" transform="matrix(2.0253 0 0 2.0253 -.20252 -105.43)"> + <g id="layer1" transform="matrix(.93437 0 0 .93437 .32004 -27.206)"> + <g id="g1751" transform="matrix(.4567 0 0 .4567 -11.042 60.847)"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#336790" style="paint-order:markers fill stroke"/> + </g> + <g id="g1747" transform="translate(0 -23.387)" stroke-width=".22458"> + <g id="text1023" fill="#336790" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> + </g> +</svg> diff --git a/docs/images/banner-negative-640x320.svg b/docs/images/banner-negative-640x320.svg new file mode 100644 index 00000000..d45698ed --- /dev/null +++ b/docs/images/banner-negative-640x320.svg @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="640" height="320" version="1.1" viewBox="0 0 169.33 84.667" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <g id="g848" transform="matrix(2.0253 0 0 2.0253 -.20252 -105.43)"> + <rect id="rect830" x=".1" y="52.059" width="83.611" height="41.805" ry="0" fill="#336790" style="paint-order:markers fill stroke"/> + <g id="layer1" transform="matrix(.93437 0 0 .93437 .32004 -27.206)"> + <g id="g1751" transform="matrix(.4567 0 0 .4567 -11.042 60.847)"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#fff" style="paint-order:markers fill stroke"/> + </g> + <g id="g1747" transform="translate(0 -23.387)" stroke-width=".22458"> + <g id="text1023" fill="#fff" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> + </g> +</svg> diff --git a/docs/images/favicon.svg b/docs/images/favicon.svg new file mode 100644 index 00000000..a1d31916 --- /dev/null +++ b/docs/images/favicon.svg @@ -0,0 +1,23 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="32" height="32" version="1.1" viewBox="0 0 8.4667 8.4667" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <style>#snake { fill: #336790 } + #background { fill: none } + #hammer { fill:#e5b62f } + + @media (prefers-color-scheme: dark) { + #snake { fill: #FFFFFF } + #background { fill: #336790 } + }</style> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <rect id="background" y="2.7838e-7" width="8.4667" height="8.4667" ry=".50736" style="paint-order:normal"/> + <path id="snake" transform="scale(.26458)" d="m19.164 0.029297c-0.88194 0.014665-1.5718 0.37353-1.9941 0.6875-0.26272 0.19532-0.41783 0.32613-0.56055 0.39844-0.14272 0.072303-0.29746 0.11633-0.64258 0.11719-0.34503 8.75e-4 -0.49969-0.039683-0.64258-0.11133-0.14289-0.071645-0.30455-0.20433-0.56836-0.39844-0.56551-0.41609-1.6221-0.9144-2.9297-0.56055-1.3076 0.35385-1.9735 1.3204-2.252 1.9648-0.12988 0.30055-0.19383 0.49294-0.28125 0.62695-0.087417 0.13401-0.20354 0.24664-0.50195 0.41992-0.29844 0.1733-0.45159 0.21312-0.61133 0.22266-0.15973 0.0095357-0.36213-0.024369-0.6875-0.060547-0.69753-0.07756-1.8647 0.022023-2.8203 0.98242-0.95556 0.96031-1.0479 2.1227-0.9668 2.8203 0.037788 0.32522 0.075118 0.52585 0.066406 0.68555-0.0087118 0.15969-0.048898 0.31398-0.2207 0.61328-0.17186 0.29938-0.28672 0.41407-0.41992 0.50195-0.1332 0.087889-0.32119 0.15574-0.62109 0.28711-0.64266 0.28151-1.6096 0.95019-1.957 2.2598-0.34742 1.3096 0.15757 2.3666 0.57617 2.9297 0.19532 0.26272 0.32613 0.41978 0.39844 0.5625 0.072304 0.14272 0.11828 0.29551 0.11914 0.64062 8.427e-4 0.34504-0.039708 0.49979-0.11133 0.64258-0.071621 0.14279-0.20432 0.29866-0.39844 0.5625-0.41617 0.56562-0.91438 1.63-0.56055 2.9375 0.35383 1.3075 1.3183 1.9656 1.9629 2.2441 0.30055 0.12988 0.49294 0.19969 0.62695 0.28711 0.13401 0.08742 0.24859 0.20354 0.42188 0.50195 0.17331 0.29846 0.21117 0.45366 0.2207 0.61328 0.00952 0.15962-0.022405 0.36018-0.058594 0.68555-0.07756 0.69753 0.021947 1.8647 0.98242 2.8203 0.96054 0.95576 2.1216 1.0478 2.8184 0.9668 0.32479-0.03776 0.52777-0.07552 0.6875-0.06641 0.15973 0.0091 0.31957 0.05069 0.61914 0.22266 0.29938 0.17186 0.40821 0.27891 0.49609 0.41211 0.087889 0.1332 0.15574 0.329 0.28711 0.62891 0.28154 0.6427 0.95026 1.5999 2.2598 1.9473 0.68097 0.18065 1.3929 0.10085 1.9473-0.05078 0.27718-0.07582 0.51383-0.17138 0.70117-0.27344 0.09367-0.05103 0.17632-0.1008 0.25195-0.16992 0.07563-0.06912 0.18398-0.15909 0.17774-0.38281-0.0045-0.15928-0.15659-0.33832-0.26562-0.38477-0.10904-0.04644-0.1808-0.04758-0.25195-0.05078-0.14232-0.0064-0.28263 0.0029-0.44922 0-0.33318-0.0058-0.73652-0.05383-1.1445-0.31055-0.90522-0.56956-0.72117-0.72807-0.97461-1.3066-0.21057-0.48069-0.64521-1.521-1.8164-2.1934-1.1713-0.67236-2.2838-0.52538-2.8047-0.46484-0.28801 0.03348-0.39727 0.05848-0.42188 0.05273-0.024608-0.0057-0.12892-0.05795-0.39062-0.31836-0.26164-0.26035-0.31078-0.35895-0.31641-0.38281-0.00563-0.02385 0.010884-0.14107 0.042969-0.42969 0.058004-0.52165 0.20538-1.6292-0.47266-2.7969-0.67803-1.1677-1.7171-1.6003-2.1992-1.8086-0.26649-0.11516-0.37278-0.15326-0.39062-0.16992s-0.081293-0.10847-0.17773-0.46484c-0.096489-0.35655-0.08929-0.46948-0.082031-0.49414 0.00726-0.02464 0.080382-0.11448 0.25195-0.34766 0.31051-0.42202 0.99165-1.3134 0.98828-2.6641-0.00329-1.3506-0.69092-2.2372-1.0039-2.6582-0.17301-0.23272-0.24275-0.32375-0.25-0.34766-0.00725-0.02393-0.014608-0.13724 0.080078-0.49414 0.094621-0.35668 0.15194-0.44794 0.16992-0.46484 0.017979-0.01689 0.12654-0.05338 0.39258-0.16992 0.48071-0.21057 1.5191-0.64521 2.1914-1.8164 0.67236-1.1713 0.52538-2.2838 0.46484-2.8047-0.033451-0.28794-0.05655-0.39526-0.050781-0.41992 0.0057827-0.02468 0.055978-0.13085 0.31641-0.39258 0.26055-0.26185 0.36074-0.31065 0.38477-0.31641 0.024038-0.00574 0.13179 0.012875 0.41992 0.044922 0.52063 0.057887 1.6386 0.19776 2.8066-0.48047 1.1678-0.67812 1.5928-1.712 1.8008-2.1934 0.11497-0.26606 0.16049-0.37226 0.17773-0.39062 0.01723-0.018368 0.10838-0.081269 0.46484-0.17773 0.35656-0.096492 0.46964-0.087296 0.49414-0.080078 0.02449 0.00722 0.10662 0.078405 0.33984 0.25 0.42203 0.31051 1.3135 0.98578 2.6641 0.98242 1.3505-0.00337 2.2454-0.68338 2.666-0.99609 0.23273-0.17302 0.31379-0.24464 0.33789-0.25195 0.02411-0.00731 0.13926-0.012632 0.49609 0.082031 0.35676 0.094642 0.44745 0.15151 0.46484 0.16992 0.01739 0.01841 0.0594 0.12495 0.17578 0.39062 0.21063 0.48084 0.64524 1.5133 1.8164 2.1855 1.1712 0.67231 2.2837 0.5254 2.8047 0.46484 0.28802-0.033487 0.39727-0.050663 0.42188-0.044922 0.0246 0.00574 0.12892 0.057957 0.39062 0.31836 0.2617 0.2604 0.31274 0.35905 0.31836 0.38281 0.0056 0.023773-0.02064 0.13333-0.05273 0.42188-0.05798 0.52147-0.1976 1.637 0.48047 2.8047 0.67812 1.1678 1.7179 1.5928 2.1992 1.8008 0.26609 0.11498 0.37412 0.15261 0.39258 0.16992 0.01844 0.01731 0.07933 0.11624 0.17578 0.47266 0.09648 0.35651 0.08927 0.46962 0.08203 0.49414-0.0073 0.02453-0.08032 0.10657-0.25195 0.33984-0.31051 0.42202-0.99164 1.3135-0.98828 2.6641 0.0034 1.3506 0.69127 2.2455 1.0039 2.666 0.17298 0.23267 0.24271 0.31577 0.25 0.33984 0.0073 0.02407 0.01461 0.13725-0.08008 0.49414-0.09465 0.35678-0.15923 0.44736-0.17773 0.46484-0.01848 0.0175-0.1172 0.06139-0.38281 0.17773-0.48071 0.21057-1.521 0.64522-2.1934 1.8164-0.67234 1.1713-0.52538 2.2838-0.46484 2.8047 0.03349 0.28802 0.05652 0.39531 0.05078 0.41992-0.0057 0.02461-0.056 0.12307-0.31641 0.38477-0.26038 0.26167-0.36085 0.31075-0.38477 0.31641-0.02392 0.0057-0.13138-0.01088-0.41992-0.04297-0.52166-0.05801-1.637-0.19952-2.8047 0.47852-1.1676 0.67802-1.6002 1.719-1.8086 2.2012-0.09505 0.21997-0.14146 0.345-0.16211 0.375-0.0078 0.01134-0.06163 0.02709-0.07422 0.03711-0.02506-0.01043-0.04775-0.01936-0.07422-0.0293-0.39901-0.15012-0.77353-0.12686-1.0332 0.0293-0.25968 0.15617-0.40837 0.34516-0.6582 0.53125-0.22497 0.16758-0.42334 0.25977-0.62695 0.42188-0.1078 0.08583-0.13134 0.27743-0.19922 0.42774-0.01406 0.0015-0.03043 0.0072-0.0293 0.0078 0.0011-5.19e-4 0.0011-0.0012-0.02148-0.05273-0.07693-0.1756-0.26331-0.43841-0.61328-0.53125-0.20104-0.05332-0.3768-0.0307-0.51758 0.0078-0.07039 0.01924-0.12868 0.04787-0.19141 0.08203-0.03137 0.01708-0.06926 0.03382-0.11133 0.07227-0.02105 0.0192-0.06446 0.07891-0.06641 0.08203-9.72e-4 0.0016-0.04249 0.08644-0.04297 0.08789-4.78e-4 0.0015-0.01566 0.12368-0.01563 0.125 3.5e-5 0.0013 0.01525 0.11022 0.01563 0.11133 3.77e-4 0.0011 0.0657 0.11042 0.06641 0.11133 0.0014 0.0018 0.14381 0.11605 0.14648 0.11719 0.0027 0.0011 0.0723 0.02559 0.0957 0.0293 0.0234 0.0037 0.04672 0.0072 0.06055 0.0078 0.05531 0.0025 0.06953-3.35e-4 0.08789 0 0.03674 6.71e-4 0.04558-3.61e-4 0.05859 0.0078 0.11488 0.07228-0.01299-0.06995 0.06641 0.11133 0.03659 0.08358 0.15732 0.37174 0.45898 0.54492 0.2858 0.16405 0.55768 0.12343 0.66406 0.11133 0.12223 0.17551 0.22708 0.38193 0.39062 0.45117 0.24961 0.10568 0.48318 0.143 0.76758 0.25 0.30905 0.11628 0.51148 0.25905 0.80469 0.33984 0.29321 0.0808 0.67005 0.01236 1.0039-0.23633 0.24494-0.18239 0.41372-0.40308 0.46484-0.65039 0.03446-0.16668-0.0068-0.29245-0.03711-0.42774 0.78889-0.45096 1.366-1.0846 1.5801-1.5801 0.12987-0.30053 0.19385-0.49304 0.28125-0.62695 0.0874-0.13391 0.2035-0.24661 0.50195-0.41992 0.29851-0.17333 0.45365-0.21892 0.61328-0.22852s0.36024 0.03024 0.68555 0.06641c0.6974 0.07753 1.8646-0.02197 2.8203-0.98242 0.95562-0.96038 1.0479-2.1307 0.9668-2.8281-0.03779-0.32515-0.07518-0.52597-0.06641-0.68555 0.0088-0.15958 0.04885-0.31391 0.2207-0.61328 0.17187-0.29941 0.28865-0.41398 0.42188-0.50195 0.13323-0.08797 0.3193-0.15576 0.61914-0.28711 0.6426-0.28148 1.6018-0.95024 1.9492-2.2598 0.34741-1.3096-0.14973-2.3588-0.56836-2.9219-0.19529-0.26267-0.32621-0.4198-0.39844-0.5625-0.07223-0.1427-0.11828-0.2974-0.11914-0.64258-8.43e-4 -0.34505 0.03969-0.49773 0.11133-0.64062 0.07164-0.1429 0.20434-0.30455 0.39844-0.56836 0.41616-0.56561 0.91438-1.6241 0.56055-2.9316-0.35385-1.3076-1.3185-1.9734-1.9629-2.2519-0.30053-0.12987-0.49304-0.1919-0.62695-0.2793-0.13391-0.087395-0.24857-0.20349-0.42188-0.50195-0.17332-0.29848-0.2111-0.45354-0.2207-0.61328-0.009603-0.15974 0.022426-0.36025 0.058594-0.68555 0.077543-0.6974-0.02007-1.8647-0.98047-2.8203-0.96035-0.95558-2.1305-1.0479-2.8281-0.9668-0.32522 0.037802-0.52011 0.075116-0.67969 0.066406s-0.31982-0.050834-0.61914-0.22266c-0.29941-0.17187-0.40617-0.28669-0.49414-0.41992-0.087972-0.13323-0.15772-0.32125-0.28906-0.62109-0.28146-0.6425-0.95603-1.6077-2.2656-1.9551-0.28592-0.075851-0.5516-0.09112-0.8125-0.095703-0.02855-0.0087601-0.05807-0.014007-0.08789-0.015625-0.0092 7.604e-5 -0.02011-1.5289e-4 -0.0293 0z" color="#000000" color-rendering="auto" dominant-baseline="auto" image-rendering="auto" shape-rendering="auto" solid-color="#000000" style="font-feature-settings:normal;font-variant-alternates:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal;font-variant-position:normal;isolation:auto;mix-blend-mode:normal;paint-order:normal;shape-padding:0;text-decoration-color:#000000;text-decoration-line:none;text-decoration-style:solid;text-indent:0;text-orientation:mixed;text-transform:none;white-space:normal"/> + <path id="hammer" transform="scale(.26458)" d="m17.178 5.8535c-0.90458-0.00858-2.5666 0.023249-2.5762 0.023437-0.36953 0-0.65625 0.32007-0.65625 0.66992v0.52539h-0.50195v-0.52539c0-0.34982-0.29651-0.66992-0.66602-0.66992h-1.8223c-0.36954 0-0.66406 0.31858-0.66406 0.66992v3.8613c0 0.35114 0.29466 0.67188 0.66406 0.67188h1.8223c0.36947 0 0.66602-0.32207 0.66602-0.67188v-0.52344h0.50195v0.52344c0 0.34986 0.28674 0.67188 0.65625 0.67188h0.40625v4.4004c-0.42951 0.35793-0.90039 0.7288-0.90039 1.3281v7.4492c0 1.07 0.87729 1.9473 1.9473 1.9473 1.07 0 1.9492-0.87714 1.9492-1.9473v-7.4492c0-0.60046-0.46946-0.97021-0.90039-1.3281v-4.4004h0.67969l0.14062-0.13281c0.2743-0.2415 0.26214-0.3581 0.39062-0.52344 0.12134-0.15616 0.30876-0.33151 0.62695-0.50195 0.97792-0.32632 1.5844-0.096178 2.0156 0.19141 0.21798 0.14536 0.38435 0.30454 0.50195 0.42774 0.0588 0.06159 0.0867 0.10559 0.16992 0.17773 0.02079 0.01803 0.04559 0.03682 0.0957 0.06641 0.02506 0.01482 0.10911 0.05004 0.11133 0.05078 0.0022 7.36e-4 0.21117 0.02363 0.21289 0.02344 8.58e-4 -8.7e-5 0.16333-0.03677 0.16406-0.03711 7.33e-4 -3.22e-4 0.13807-0.09514 0.13867-0.0957 0.0012-0.0011 0.13991-0.22055 0.14063-0.22266 7.18e-4 -0.0021 0.02688-0.09873 0.0293-0.13281 0.0024-0.03409 0.0014-0.05869 0-0.08008-0.0126-0.20888-0.08797-0.32205-0.11524-0.42188-0.32614-0.76148-0.35937-2.1118-2.2988-3.1367l-0.01367-0.00781-0.01563-0.00781c-0.44578-0.2005-0.92355-0.40081-1.3359-0.55274-0.2062-0.075966-0.39695-0.13657-0.56055-0.18555-0.1205-0.036072-0.2224-0.055177-0.33203-0.072266-0.0052-8.054e-4 -0.01037-0.00706-0.01563-0.00781-0.0243-0.00677-0.04332-0.01279-0.05859-0.015625-0.01822-0.00334-0.03075-0.00412-0.04492-0.00586-0.0096-0.00119-0.02019-0.00691-0.0293-0.00781-0.04519-0.00461-0.08879-0.00551-0.14062-0.00781-0.10369-0.00461-0.23158-0.00638-0.38281-0.00781z" style="paint-order:markers fill stroke"/> +</svg> diff --git a/docs/images/logo-demo-editable-inkscape.svg b/docs/images/logo-demo-editable-inkscape.svg new file mode 100644 index 00000000..45969b11 --- /dev/null +++ b/docs/images/logo-demo-editable-inkscape.svg @@ -0,0 +1,888 @@ +<?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:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="242.69724mm" + height="125.92096mm" + viewBox="0 0 242.69724 125.92096" + version="1.1" + id="svg1021" + inkscape:version="0.92.4 (5da689c313, 2019-01-14)" + sodipodi:docname="demo-editable-inkscape.svg"> + <defs + id="defs1015" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.4" + inkscape:cx="538.4224" + inkscape:cy="174.08239" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + fit-margin-top="0.5" + fit-margin-left="0.5" + fit-margin-right="0.5" + fit-margin-bottom="0.5" + inkscape:window-width="2560" + inkscape:window-height="1387" + inkscape:window-x="1072" + inkscape:window-y="-8" + inkscape:window-maximized="1" /> + <metadata + id="metadata1018"> + <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(113.7608,-68.445953)"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.75281364;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect1633" + width="64.384338" + height="60.551601" + x="-113.2608" + y="133.31531" + ry="1.57368" /> + <rect + ry="1.57368" + y="68.945953" + x="-113.2608" + height="60.551601" + width="64.384338" + id="rect1616" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.75281364;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <g + id="g982" + transform="translate(-136.29066,-7.980786)"> + <g + id="g960"> + <g + id="g945"> + <rect + ry="2.0095572" + y="100.62229" + x="53.291348" + height="14.468813" + width="4.0191145" + id="rect934" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <rect + ry="0.41858676" + y="93.042908" + x="54.55695" + height="10.046045" + width="1.4879318" + id="rect936" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <path + sodipodi:nodetypes="ssssssccsscccccssccsss" + inkscape:connector-curvature="0" + id="path938" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + </g> + <g + id="g950"> + <path + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" + inkscape:transform-center-y="0.11269997" + inkscape:transform-center-x="-0.011614295" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:randomized="0" + inkscape:rounded="0.5" + inkscape:flatsided="false" + sodipodi:arg2="2.2923522" + sodipodi:arg1="1.2451547" + sodipodi:r2="5.736691" + sodipodi:r1="7.6796398" + sodipodi:cy="71.820686" + sodipodi:cx="64.20871" + sodipodi:sides="3" + id="path944" + style="fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + sodipodi:type="star" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + id="path946" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccssszzsccc" /> + <path + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" + inkscape:connector-curvature="0" + id="path942" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + </g> + </g> + <g + id="g966"> + <text + id="text1023" + y="134.70683" + x="24.929686" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#336790;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#336790;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="24.929686" + id="tspan1021" + sodipodi:role="line">SETUP</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#e5b62f;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="54.844803" + y="134.70683" + id="text1661"><tspan + sodipodi:role="line" + id="tspan1659" + x="54.844803" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#e5b62f;fill-opacity:1;stroke-width:0.22458273">TOOLS</tspan></text> + </g> + </g> + <g + transform="translate(-136.29066,56.388565)" + id="g933" + style="fill:#000000"> + <g + id="g921" + style="fill:#000000"> + <g + id="g911" + style="fill:#000000;stroke:#000000"> + <rect + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect905" + width="4.0191145" + height="14.468813" + x="53.291348" + y="100.62229" + ry="2.0095572" /> + <rect + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect907" + width="1.4879318" + height="10.046045" + x="54.55695" + y="93.042908" + ry="0.41858676" /> + <path + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + id="path909" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ssssssccsscccccssccsss" /> + </g> + <g + id="g919" + style="fill:#000000"> + <path + sodipodi:type="star" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="path913" + sodipodi:sides="3" + sodipodi:cx="64.20871" + sodipodi:cy="71.820686" + sodipodi:r1="7.6796398" + sodipodi:r2="5.736691" + sodipodi:arg1="1.2451547" + sodipodi:arg2="2.2923522" + inkscape:flatsided="false" + inkscape:rounded="0.5" + inkscape:randomized="0" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:transform-center-x="-0.011614295" + inkscape:transform-center-y="0.11269997" + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" /> + <path + sodipodi:nodetypes="ccssszzsccc" + inkscape:connector-curvature="0" + id="path915" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + id="path917" + inkscape:connector-curvature="0" + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" /> + </g> + </g> + <g + id="g931" + style="fill:#000000"> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="24.929686" + y="134.70683" + id="text925"><tspan + sodipodi:role="line" + id="tspan923" + x="24.929686" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke-width:0.22458273">SETUP</tspan></text> + <text + id="text929" + y="134.70683" + x="54.844803" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="54.844803" + id="tspan927" + sodipodi:role="line">TOOLS</tspan></text> + </g> + </g> + <g + id="g987" + transform="matrix(0.53757651,0,0,0.53757651,2.5994897,54.191161)"> + <rect + style="fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1.40038419;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect830" + width="119.76777" + height="112.63811" + x="-71.135506" + y="27.446875" + ry="2.9273603" /> + <g + transform="matrix(1.8602003,0,0,1.8602003,-113.97566,-115.65227)" + id="g963"> + <g + id="g951"> + <g + id="g941"> + <rect + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect935" + width="4.0191145" + height="14.468813" + x="53.291348" + y="100.62229" + ry="2.0095572" /> + <rect + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect937" + width="1.4879318" + height="10.046045" + x="54.55695" + y="93.042908" + ry="0.41858676" /> + <path + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + id="path939" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ssssssccsscccccssccsss" /> + </g> + <g + style="fill:#ffffff" + id="g949"> + <path + sodipodi:type="star" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="path943" + sodipodi:sides="3" + sodipodi:cx="64.20871" + sodipodi:cy="71.820686" + sodipodi:r1="7.6796398" + sodipodi:r2="5.736691" + sodipodi:arg1="1.2451547" + sodipodi:arg2="2.2923522" + inkscape:flatsided="false" + inkscape:rounded="0.5" + inkscape:randomized="0" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:transform-center-x="-0.011614295" + inkscape:transform-center-y="0.11269997" + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" /> + <path + sodipodi:nodetypes="ccssszzsccc" + inkscape:connector-curvature="0" + id="path945" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + id="path947" + inkscape:connector-curvature="0" + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" /> + </g> + </g> + <g + id="g961"> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="24.929686" + y="134.70683" + id="text955"><tspan + sodipodi:role="line" + id="tspan953" + x="24.929686" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.22458273">SETUP</tspan></text> + <text + id="text959" + y="134.70683" + x="54.844803" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#e5b62f;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#e5b62f;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="54.844803" + id="tspan957" + sodipodi:role="line">TOOLS</tspan></text> + </g> + </g> + </g> + <g + transform="matrix(0.53757651,0,0,0.53757651,2.5994897,118.56051)" + id="g1068"> + <rect + ry="2.9273603" + y="27.446875" + x="-71.135506" + height="112.63811" + width="119.76777" + id="rect1036" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1.40038419;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <g + id="g1066" + transform="matrix(1.8602003,0,0,1.8602003,-113.97566,-115.65227)"> + <g + id="g1054"> + <g + id="g1044" + style="fill:#ffffff;stroke:#ffffff"> + <rect + ry="2.0095572" + y="100.62229" + x="53.291348" + height="14.468813" + width="4.0191145" + id="rect1038" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#ffffff;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <rect + ry="0.41858676" + y="93.042908" + x="54.55695" + height="10.046045" + width="1.4879318" + id="rect1040" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#ffffff;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <path + sodipodi:nodetypes="ssssssccsscccccssccsss" + inkscape:connector-curvature="0" + id="path1042" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#ffffff;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + </g> + <g + id="g1052" + style="fill:#ffffff"> + <path + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" + inkscape:transform-center-y="0.11269997" + inkscape:transform-center-x="-0.011614295" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:randomized="0" + inkscape:rounded="0.5" + inkscape:flatsided="false" + sodipodi:arg2="2.2923522" + sodipodi:arg1="1.2451547" + sodipodi:r2="5.736691" + sodipodi:r1="7.6796398" + sodipodi:cy="71.820686" + sodipodi:cx="64.20871" + sodipodi:sides="3" + id="path1046" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + sodipodi:type="star" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + id="path1048" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccssszzsccc" /> + <path + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" + inkscape:connector-curvature="0" + id="path1050" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + </g> + </g> + <g + id="g1064"> + <text + id="text1058" + y="134.70683" + x="24.929686" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="24.929686" + id="tspan1056" + sodipodi:role="line">SETUP</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="54.844803" + y="134.70683" + id="text1062"><tspan + sodipodi:role="line" + id="tspan1060" + x="54.844803" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.22458273">TOOLS</tspan></text> + </g> + </g> + </g> + <g + id="g1580"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.48264033;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect830-6-9" + width="83.610924" + height="23.210442" + x="44.825508" + y="70.721588" + ry="0.51978147" /> + <g + transform="translate(-2.4460125,-38.175599)" + id="g1166"> + <g + id="g1086" + transform="matrix(0.45669608,0,0,0.45669608,33.528721,74.147264)"> + <g + id="g1076"> + <rect + ry="2.0095572" + y="100.62229" + x="53.291348" + height="14.468813" + width="4.0191145" + id="rect1070" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <rect + ry="0.41858676" + y="93.042908" + x="54.55695" + height="10.046045" + width="1.4879318" + id="rect1072" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <path + sodipodi:nodetypes="ssssssccsscccccssccsss" + inkscape:connector-curvature="0" + id="path1074" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + </g> + <g + id="g1084"> + <path + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" + inkscape:transform-center-y="0.11269997" + inkscape:transform-center-x="-0.011614295" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:randomized="0" + inkscape:rounded="0.5" + inkscape:flatsided="false" + sodipodi:arg2="2.2923522" + sodipodi:arg1="1.2451547" + sodipodi:r2="5.736691" + sodipodi:r1="7.6796398" + sodipodi:cy="71.820686" + sodipodi:cx="64.20871" + sodipodi:sides="3" + id="path1078" + style="fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + sodipodi:type="star" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + id="path1080" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccssszzsccc" /> + <path + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" + inkscape:connector-curvature="0" + id="path1082" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + </g> + </g> + <g + id="g1096" + transform="translate(44.570721,-10.087076)"> + <text + id="text1090" + y="134.70683" + x="24.929686" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#336790;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#336790;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="24.929686" + id="tspan1088" + sodipodi:role="line">SETUP</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#e5b62f;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="54.844803" + y="134.70683" + id="text1094"><tspan + sodipodi:role="line" + id="tspan1092" + x="54.844803" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#e5b62f;fill-opacity:1;stroke-width:0.22458273">TOOLS</tspan></text> + </g> + </g> + <g + transform="translate(6.6817366,-57.821246)" + id="g1220"> + <rect + style="fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.48264033;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect830-6" + width="83.610924" + height="23.210442" + x="38.143772" + y="160.72751" + ry="0.51978147" /> + <g + transform="translate(-9.1277491,51.830322)" + id="g1196"> + <g + id="g1184" + transform="matrix(0.45669608,0,0,0.45669608,33.528721,74.147264)"> + <g + id="g1174"> + <rect + ry="2.0095572" + y="100.62229" + x="53.291348" + height="14.468813" + width="4.0191145" + id="rect1168" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <rect + ry="0.41858676" + y="93.042908" + x="54.55695" + height="10.046045" + width="1.4879318" + id="rect1170" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <path + sodipodi:nodetypes="ssssssccsscccccssccsss" + inkscape:connector-curvature="0" + id="path1172" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + </g> + <g + id="g1182"> + <path + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" + inkscape:transform-center-y="0.11269997" + inkscape:transform-center-x="-0.011614295" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:randomized="0" + inkscape:rounded="0.5" + inkscape:flatsided="false" + sodipodi:arg2="2.2923522" + sodipodi:arg1="1.2451547" + sodipodi:r2="5.736691" + sodipodi:r1="7.6796398" + sodipodi:cy="71.820686" + sodipodi:cx="64.20871" + sodipodi:sides="3" + id="path1176" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + sodipodi:type="star" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + id="path1178" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccssszzsccc" /> + <path + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" + inkscape:connector-curvature="0" + id="path1180" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + </g> + </g> + <g + id="g1194" + transform="translate(44.570721,-10.087076)"> + <text + id="text1188" + y="134.70683" + x="24.929686" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="24.929686" + id="tspan1186" + sodipodi:role="line">SETUP</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#e5b62f;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="54.844803" + y="134.70683" + id="text1192"><tspan + sodipodi:role="line" + id="tspan1190" + x="54.844803" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#e5b62f;fill-opacity:1;stroke-width:0.22458273">TOOLS</tspan></text> + </g> + </g> + </g> + </g> + <g + id="g1614"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.48264033;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect830-6-9-8" + width="83.610924" + height="23.210442" + x="44.825508" + y="135.09094" + ry="0.51978147" /> + <g + id="g1250" + transform="translate(-2.4460125,26.193752)"> + <g + transform="matrix(0.45669608,0,0,0.45669608,33.528721,74.147264)" + id="g1238"> + <g + style="fill:#000000;stroke:#000000" + id="g1228"> + <rect + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect1222" + width="4.0191145" + height="14.468813" + x="53.291348" + y="100.62229" + ry="2.0095572" /> + <rect + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect1224" + width="1.4879318" + height="10.046045" + x="54.55695" + y="93.042908" + ry="0.41858676" /> + <path + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + id="path1226" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ssssssccsscccccssccsss" /> + </g> + <g + style="fill:#000000" + id="g1236"> + <path + sodipodi:type="star" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="path1230" + sodipodi:sides="3" + sodipodi:cx="64.20871" + sodipodi:cy="71.820686" + sodipodi:r1="7.6796398" + sodipodi:r2="5.736691" + sodipodi:arg1="1.2451547" + sodipodi:arg2="2.2923522" + inkscape:flatsided="false" + inkscape:rounded="0.5" + inkscape:randomized="0" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:transform-center-x="-0.011614295" + inkscape:transform-center-y="0.11269997" + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" /> + <path + sodipodi:nodetypes="ccssszzsccc" + inkscape:connector-curvature="0" + id="path1232" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + id="path1234" + inkscape:connector-curvature="0" + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" /> + </g> + </g> + <g + style="fill:#000000" + transform="translate(44.570721,-10.087076)" + id="g1248"> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="24.929686" + y="134.70683" + id="text1242"><tspan + sodipodi:role="line" + id="tspan1240" + x="24.929686" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke-width:0.22458273">SETUP</tspan></text> + <text + id="text1246" + y="134.70683" + x="54.844803" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="54.844803" + id="tspan1244" + sodipodi:role="line">TOOLS</tspan></text> + </g> + </g> + <g + id="g1284" + transform="translate(6.6817366,6.5481043)"> + <rect + ry="0.51978147" + y="160.72751" + x="38.143772" + height="23.210442" + width="83.610924" + id="rect1252" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.48264033;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" /> + <g + id="g1282" + transform="translate(-9.1277491,51.830322)"> + <g + transform="matrix(0.45669608,0,0,0.45669608,33.528721,74.147264)" + id="g1270"> + <g + style="fill:#ffffff;stroke:#ffffff" + id="g1260"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#ffffff;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect1254" + width="4.0191145" + height="14.468813" + x="53.291348" + y="100.62229" + ry="2.0095572" /> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#ffffff;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect1256" + width="1.4879318" + height="10.046045" + x="54.55695" + y="93.042908" + ry="0.41858676" /> + <path + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#ffffff;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + id="path1258" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ssssssccsscccccssccsss" /> + </g> + <g + id="g1268"> + <path + sodipodi:type="star" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="path1262" + sodipodi:sides="3" + sodipodi:cx="64.20871" + sodipodi:cy="71.820686" + sodipodi:r1="7.6796398" + sodipodi:r2="5.736691" + sodipodi:arg1="1.2451547" + sodipodi:arg2="2.2923522" + inkscape:flatsided="false" + inkscape:rounded="0.5" + inkscape:randomized="0" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:transform-center-x="-0.011614295" + inkscape:transform-center-y="0.11269997" + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" /> + <path + sodipodi:nodetypes="ccssszzsccc" + inkscape:connector-curvature="0" + id="path1264" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + id="path1266" + inkscape:connector-curvature="0" + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" /> + </g> + </g> + <g + style="fill:#ffffff" + transform="translate(44.570721,-10.087076)" + id="g1280"> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="24.929686" + y="134.70683" + id="text1274"><tspan + sodipodi:role="line" + id="tspan1272" + x="24.929686" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.22458273">SETUP</tspan></text> + <text + id="text1278" + y="134.70683" + x="54.844803" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="54.844803" + id="tspan1276" + sodipodi:role="line">TOOLS</tspan></text> + </g> + </g> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo-demo.svg b/docs/images/logo-demo.svg new file mode 100644 index 00000000..6b78ebc3 --- /dev/null +++ b/docs/images/logo-demo.svg @@ -0,0 +1,150 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="242.7mm" height="125.92mm" version="1.1" viewBox="0 0 242.7 125.92" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <g id="layer1" transform="translate(113.76 -68.446)"> + <path id="rect1633" d="m-111.69 133.32h61.237c0.87182 0 1.5737 0.70186 1.5737 1.5737v57.404c0 0.87182-0.70186 1.5737-1.5737 1.5737h-61.237c-0.87182 0-1.5737-0.70186-1.5737-1.5737v-57.404c0-0.87182 0.70186-1.5737 1.5737-1.5737z" fill="#fff" style="paint-order:markers fill stroke"/> + <path id="rect1616" d="m-111.69 68.946h61.237c0.87182 0 1.5737 0.70186 1.5737 1.5737v57.404c0 0.87182-0.70186 1.5737-1.5737 1.5737h-61.237c-0.87182 0-1.5737-0.70186-1.5737-1.5737v-57.404c0-0.87182 0.70186-1.5737 1.5737-1.5737z" fill="#fff" style="paint-order:markers fill stroke"/> + <path id="rect934" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m129.77 43.688c-4.7073-0.044694-13.613 0.13281-13.613 0.13281-0.43194 0-0.77929 0.36438-0.77929 0.81445v5.5254h-8.1113v-5.5254c0-0.45012-0.34735-0.81445-0.7793-0.81445h-9.6719c-0.43195 0-0.7793 0.36438-0.7793 0.81445v20.48c0 0.45012 0.34707 0.8125 0.7793 0.8125h9.6719c0.43195 0 0.7793-0.36232 0.7793-0.8125v-5.5254h8.1113v5.5254c0 0.45012 0.34739 0.8125 0.77929 0.8125h4.8945v26.061c-2.8064 1.1139-4.7832 3.8423-4.7832 7.0547v39.494c0 4.2077 3.388 7.5957 7.5957 7.5957 4.2077 0 7.5957-3.388 7.5957-7.5957v-39.494c0-3.2119-1.9775-5.9405-4.7832-7.0547v-26.061h5.3008c0.84434-0.74337 1.6581-3.7262 6.168-6.0059 12.111-4.1603 17.37 6.1474 17.277 4.7246-0.09865-1.519-0.7716-11.047-11.346-16.635-4.6068-2.0716-10.023-4.1068-11.484-4.1914-0.15078-0.079455-1.2532-0.11791-2.8223-0.13281z" fill="#e5b62f" stroke="#e5b62f" stroke-width="1.8045" style="paint-order:markers fill stroke"/> + <path id="path944" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m140.35 12.014c-4.1549 0.06908-7.4443 1.7901-9.4395 3.2734-2.6602 1.9777-3.5133 3.1091-7.5371 3.1191-4.0238 0.010205-4.8769-1.1215-7.5469-3.0859-2.6699-1.9645-7.6448-4.3321-13.881-2.6445-6.2361 1.6876-9.3375 6.2423-10.652 9.2852-1.3149 3.0428-1.4871 4.4482-4.9668 6.4688-3.4797 2.0206-4.7856 1.4757-8.0801 1.1094-3.2945-0.36631-8.7928 0.065007-13.35 4.6445-4.5568 4.5795-4.9647 10.08-4.582 13.373 0.38259 3.2926 0.93482 4.5962-1.0684 8.0859-2.0032 3.4897-3.4032 3.6661-6.4395 4.9961-3.0363 1.33-7.5798 4.449-9.2363 10.693-1.6566 6.2444 0.74506 11.207 2.7227 13.867 1.9777 2.6602 3.1072 3.5133 3.1172 7.5371 0.011339 4.0238-1.1195 4.8769-3.084 7.5469-1.9645 2.67-4.3321 7.6448-2.6445 13.881 1.6876 6.236 6.2423 9.3374 9.2852 10.652 3.0428 1.3149 4.4482 1.4871 6.4688 4.9668 2.0205 3.4797 1.4757 4.7856 1.1094 8.0801-0.36631 3.2945 0.062774 8.7928 4.6426 13.35 4.5795 4.5568 10.08 4.9549 13.373 4.5723 3.2926-0.38272 4.5962-0.9251 8.0859 1.0781 3.4897 2.0032 3.668 3.4032 4.998 6.4394 1.33 3.0362 4.447 7.5798 10.691 9.2363 6.2444 1.6565 13.901-1.5082 13.867-2.7226-0.03439-1.2144-5.1602 0.87503-10.301-2.3594-5.1406-3.2344-4.7729-5.2312-5.9062-7.8184-1.1333-2.5872-3.1606-7.4448-8.8164-10.691-5.6557-3.2466-10.868-2.5429-13.674-2.2168-2.8057 0.32617-2.9932 0.89285-5.8887-1.9883-2.8955-2.8812-2.3199-3.0638-2.0078-5.8711 0.31219-2.8073 0.98369-8.0206-2.291-13.66-3.2747-5.6395-8.1377-7.6472-10.73-8.7676-2.5928-1.1204-3.0365-0.71142-4.1035-4.6543-1.067-3.943-0.4865-3.8284 1.1875-6.1035 1.6739-2.2751 4.8698-6.4494 4.8535-12.971-0.015874-6.5213-3.2327-10.692-4.918-12.959-1.6852-2.2667-2.2701-2.1417-1.2227-6.0898 1.0474-3.9482 1.4987-3.5405 4.0859-4.6738 2.5872-1.1333 7.4448-3.1626 10.691-8.8184 3.2466-5.6557 2.5429-10.868 2.2168-13.674-0.32591-2.8057-0.89483-2.9932 1.9863-5.8887 2.8812-2.8955 3.0638-2.3297 5.8711-2.0176 2.8072 0.31211 8.0226 0.99541 13.662-2.2793 5.6395-3.2747 7.6354-8.1376 8.7559-10.73 1.1204-2.5928 0.72115-3.0365 4.6641-4.1035 3.9429-1.067 3.8284-0.48836 6.1035 1.1855 2.2751 1.6739 6.4514 4.8717 12.973 4.8555 6.5213-0.016252 10.681-3.2347 12.947-4.9199 2.2667-1.6852 2.1417-2.2701 6.0898-1.2227 3.9482 1.0474 3.5522 1.4987 4.6855 4.0859 1.1333 2.5872 3.1607 7.4448 8.8164 10.691s10.87 2.5429 13.676 2.2168c2.8057-0.3261 2.9932-0.89287 5.8887 1.9883s2.318 3.0638 2.0059 5.8711c-0.31211 2.8072-0.98369 8.0207 2.291 13.66 3.2747 5.6395 8.1376 7.6355 10.73 8.7559 2.5928 1.1204 3.0365 0.72311 4.1035 4.666 1.067 3.9429 0.48642 3.8284-1.1875 6.1035-1.6739 2.2751-4.8697 6.4494-4.8535 12.971 0.01625 6.5213 3.2327 10.681 4.918 12.947 1.6852 2.2667 2.27 2.1436 1.2226 6.0918-1.0474 3.9482-1.4968 3.5503-4.084 4.6836-2.5872 1.1333-7.4448 3.1626-10.691 8.8184-3.2466 5.6557-2.5448 10.868-2.2188 13.674 0.3261 2.8056 0.89483 2.9932-1.9863 5.8887-2.8812 2.8955-3.0638 2.32-5.8711 2.0078-2.8072-0.31219-8.0206-0.9856-13.66 2.2891-5.6395 3.2747-7.6472 8.1376-8.7676 10.73-0.93129 2.1552-0.84174 2.8278-3.0371 3.6055-0.31286-0.1736-0.67425-0.33971-1.1055-0.50195-3.6364-1.3682-4.115 0.48194-7.0996 2.7051-2.684 1.9992-4.6031 2.234-4.4902 4.8711-0.25407-0.02563-0.4922-0.03006-0.68359-0.00781-0.60936 0.07067-0.85026 0.17155-1.4961-0.19922s-0.67964-0.63142-0.92579-1.1934c-0.24616-0.56187-0.82291-1.4024-1.9785-1.709-1.1557-0.30652-2.5727 0.2791-2.5664 0.50391 0.00643 0.2245 0.95492-0.16129 1.9062 0.4375 0.95134 0.5986 0.88402 0.96652 1.0938 1.4453 0.20965 0.47887 0.5842 1.3796 1.6309 1.9805 1.0467 0.60083 2.012 0.47055 2.5312 0.41016 0.39726-0.04627 0.51372-0.11363 0.78516 0.09375 0.79695 2.7289 2.7246 2.4282 6.0664 3.6855 3.6364 1.3682 4.7478 3.0142 7.7324 0.79102 2.1873-1.6292 1.9673-2.8055 1.4394-4.7266 4.8594-2.0322 7.4092-5.8859 8.5684-8.5684 1.3149-3.0428 1.4871-4.4482 4.9668-6.4688 3.4797-2.0206 4.7875-1.4757 8.082-1.1094 3.2945 0.36624 8.7908-0.06484 13.348-4.6445 4.5568-4.5795 4.9667-10.08 4.584-13.373-0.38271-3.2926-0.93681-4.5962 1.0664-8.0859 2.0032-3.4897 3.4032-3.666 6.4395-4.9961 3.0362-1.33 7.5817-4.449 9.2383-10.693 1.6565-6.2444-0.74494-11.207-2.7227-13.867-1.9777-2.6601-3.1091-3.5133-3.1191-7.5371-0.00983-4.0238 1.1195-4.8769 3.084-7.5469 1.9645-2.6699 4.3341-7.6448 2.6465-13.881-1.6876-6.2361-6.2423-9.3375-9.2852-10.652s-4.4502-1.4852-6.4707-4.9648-1.4737-4.7876-1.1074-8.082c0.36631-3.2945-0.065-8.7928-4.6445-13.35-4.5795-4.5568-10.08-4.9647-13.373-4.582-3.2926 0.38271-4.5962 0.93681-8.0859-1.0664-3.4897-2.0032-3.6661-3.4032-4.9961-6.4395-1.33-3.0363-4.449-7.5817-10.693-9.2383-1.5611-0.41413-3.0428-0.57381-4.4277-0.55078z" fill="#336790" style="paint-order:markers fill stroke"/> + <g id="text1023" fill="#336790" stroke-width=".22458" aria-label="SETUP"> + <path id="path1513" d="m-108.11 126.82q-0.95915 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14622-0.28073-0.41525-0.386-0.1696-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.164 0.14621v1.4095q-1.4212-0.15206-2.164-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25148 0.25733-0.0877 0.15791-0.12867 0.32167-0.0351 0.16376-0.0351 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61994 0.30413 0.38015 0.4211 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70183 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1515" d="m-104.26 118.49h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1517" d="m-93.406 118.49v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1519" d="m-92.663 118.49h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29243-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52051-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1521" d="m-84.809 119.89v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446 0-0.44448-0.23979-0.75446-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52637 0.66673 0.52637 1.6376t-0.52637 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1524" d="m-75.457 118.49v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1526" d="m-73.223 121.1q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60824-1.6668 0.60824-1.0176 0-1.6668-0.60824-0.64918-0.6141-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1528" d="m-67.24 121.1q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60824-1.6668 0.60824-1.0176 0-1.6668-0.60824-0.64918-0.6141-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1530" d="m-62.374 126.73v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1532" d="m-54.262 126.82q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.08773 0.15791-0.12867 0.32167-0.03509 0.16376-0.03509 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <path id="rect905" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m129.77 286.97c-4.7073-0.0447-13.613 0.13476-13.613 0.13476-0.43194 0-0.77929 0.36236-0.77929 0.8125v5.5274h-8.1113v-5.5274c0-0.4501-0.34735-0.8125-0.7793-0.8125h-9.6719c-0.43195 0-0.7793 0.36236-0.7793 0.8125v20.482c0 0.45011 0.34707 0.81055 0.7793 0.81055h9.6719c0.43195 0 0.7793-0.36052 0.7793-0.81055v-5.5273h8.1113v5.5273c0 0.45011 0.34739 0.81055 0.77929 0.81055h4.8945v26.061c-2.8064 1.1138-4.7832 3.8423-4.7832 7.0547v39.496c0 4.2078 3.388 7.5938 7.5957 7.5938 4.2077 0 7.5957-3.386 7.5957-7.5938v-39.496c0-3.2119-1.9775-5.9405-4.7832-7.0547v-26.061h5.3008c0.84434-0.74336 1.6581-3.7242 6.168-6.0039 12.111-4.1602 17.37 6.1455 17.277 4.7227-0.09865-1.519-0.7716-11.045-11.346-16.633-4.6068-2.0716-10.023-4.1068-11.484-4.1914-0.15078-0.07946-1.2532-0.11986-2.8223-0.13476z" stroke="#000" stroke-width="1.8045" style="paint-order:markers fill stroke"/> + <path id="path913" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m140.35 255.3c-4.1549 0.06908-7.4443 1.7902-9.4395 3.2734-2.6602 1.9777-3.5133 3.1091-7.5371 3.1191-4.0238 0.01133-4.8769-1.1195-7.5469-3.084-2.6699-1.9645-7.6448-4.3321-13.881-2.6445-6.2361 1.6876-9.3375 6.2404-10.652 9.2832-1.3149 3.0428-1.4871 4.4502-4.9668 6.4707-3.4797 2.0206-4.7856 1.4737-8.0801 1.1074-3.2945-0.36624-8.7928 0.06484-13.35 4.6445-4.5568 4.5795-4.9647 10.08-4.582 13.373 0.38259 3.2926 0.93482 4.5962-1.0684 8.0859-2.0032 3.4897-3.4032 3.6661-6.4395 4.9961-3.0363 1.33-7.5798 4.4489-9.2363 10.693-1.6566 6.2444 0.74506 11.207 2.7227 13.867 1.9777 2.6601 3.1072 3.5133 3.1172 7.5371 0.011339 4.0238-1.1195 4.8789-3.084 7.5488-1.9645 2.67-4.3321 7.6428-2.6445 13.879 1.6876 6.2361 6.2423 9.3374 9.2852 10.652 3.0428 1.3149 4.4482 1.4871 6.4688 4.9668 2.0205 3.4797 1.4757 4.7875 1.1094 8.082-0.36631 3.2945 0.062774 8.7908 4.6426 13.348 4.5795 4.5568 10.08 4.9549 13.373 4.5723 3.2926-0.38271 4.5962-0.92514 8.0859 1.0781 3.4897 2.0032 3.668 3.4032 4.998 6.4394 1.33 3.0363 4.447 7.5797 10.691 9.2363 6.2444 1.6565 13.901-1.5063 13.867-2.7207-0.03439-1.2144-5.1602 0.87304-10.301-2.3613-5.1406-3.2344-4.7729-5.2312-5.9062-7.8184-1.1333-2.5872-3.1606-7.4448-8.8164-10.691-5.6557-3.2466-10.868-2.5429-13.674-2.2168-2.8057 0.32618-2.9932 0.89481-5.8887-1.9863-2.8955-2.8812-2.3199-3.0638-2.0078-5.8711 0.31219-2.8073 0.98369-8.0226-2.291-13.662-3.2747-5.6395-8.1377-7.6452-10.73-8.7656-2.5928-1.1204-3.0365-0.71142-4.1035-4.6543-1.067-3.943-0.4865-3.8303 1.1875-6.1055 1.6739-2.2751 4.8698-6.4494 4.8535-12.971-0.015874-6.5214-3.2327-10.69-4.918-12.957-1.6852-2.2667-2.2701-2.1436-1.2227-6.0918 1.0474-3.9482 1.4987-3.5405 4.0859-4.6738 2.5872-1.1333 7.4448-3.1606 10.691-8.8164 3.2466-5.6557 2.5429-10.87 2.2168-13.676-0.32591-2.8057-0.89483-2.9931 1.9863-5.8887 2.8812-2.8955 3.0638-2.3297 5.8711-2.0176 2.8072 0.31219 8.0226 0.9954 13.662-2.2793 5.6395-3.2747 7.6354-8.1377 8.7559-10.73 1.1204-2.5928 0.72115-3.0365 4.6641-4.1035 3.9429-1.067 3.8284-0.48641 6.1035 1.1875 2.2751 1.6739 6.4514 4.8697 12.973 4.8535 6.5213-0.01512 10.681-3.2328 12.947-4.918 2.2667-1.6852 2.1417-2.2701 6.0898-1.2226 3.9482 1.0474 3.5522 1.4967 4.6855 4.084 1.1333 2.5872 3.1607 7.4448 8.8164 10.691 5.6557 3.2466 10.87 2.5448 13.676 2.2188 2.8057-0.32618 2.9932-0.89485 5.8887 1.9863 2.8955 2.8811 2.318 3.0638 2.0059 5.8711-0.31211 2.8072-0.98369 8.0206 2.291 13.66 3.2747 5.6395 8.1376 7.6355 10.73 8.7559 2.5928 1.1205 3.0365 0.7231 4.1035 4.666 1.067 3.9429 0.48642 3.8284-1.1875 6.1035-1.6739 2.2751-4.8697 6.4494-4.8535 12.971 0.01625 6.5213 3.2327 10.682 4.918 12.949 1.6852 2.2667 2.27 2.1417 1.2226 6.0898-1.0474 3.9482-1.4968 3.5522-4.084 4.6856-2.5872 1.1333-7.4448 3.1607-10.691 8.8164-3.2466 5.6557-2.5448 10.868-2.2188 13.674 0.3261 2.8057 0.89483 2.9932-1.9863 5.8887-2.8812 2.8955-3.0638 2.32-5.8711 2.0078-2.8072-0.31219-8.0206-0.98365-13.66 2.291-5.6395 3.2747-7.6472 8.1376-8.7676 10.73-0.93126 2.1551-0.84198 2.8259-3.0371 3.6035-0.31272-0.17348-0.67455-0.33983-1.1055-0.50196-3.6364-1.3681-4.115 0.48194-7.0996 2.7051-2.6846 1.9997-4.6041 2.2342-4.4902 4.873-0.2541-0.02564-0.49218-0.03202-0.68359-0.00977-0.60936 0.07068-0.85026 0.17156-1.4961-0.19922-0.64583-0.37077-0.67964-0.62946-0.92579-1.1914-0.24616-0.56187-0.82291-1.4044-1.9785-1.7109-1.1557-0.30652-2.5727 0.2791-2.5664 0.50391 0.00643 0.2245 0.95492-0.16129 1.9062 0.4375 0.95134 0.5986 0.88402 0.96847 1.0938 1.4473 0.20965 0.47887 0.5842 1.3777 1.6309 1.9785 1.0467 0.60083 2.012 0.47055 2.5312 0.41015 0.39726-0.04626 0.51372-0.11362 0.78516 0.09375 0.79695 2.7289 2.7246 2.4282 6.0664 3.6856 3.6364 1.3682 4.7478 3.0142 7.7324 0.79102 2.1872-1.6292 1.9673-2.8037 1.4394-4.7246 4.8594-2.0321 7.4092-5.8859 8.5684-8.5684 1.3149-3.0428 1.4871-4.4502 4.9668-6.4707 3.4797-2.0206 4.7875-1.4757 8.082-1.1094 3.2945 0.36624 8.7908-0.06293 13.348-4.6426 4.5568-4.5795 4.9667-10.082 4.584-13.375-0.38271-3.2926-0.93681-4.5942 1.0664-8.084 2.0032-3.4896 3.4032-3.668 6.4395-4.998 3.0362-1.33 7.5817-4.447 9.2383-10.691 1.6565-6.2443-0.74494-11.207-2.7227-13.867-1.9777-2.6602-3.1091-3.5133-3.1191-7.5371-0.00983-4.0237 1.1195-4.8789 3.084-7.5488 1.9645-2.6699 4.3341-7.6448 2.6465-13.881-1.6876-6.236-6.2423-9.3355-9.2852-10.65-3.0428-1.3149-4.4502-1.4871-6.4707-4.9668-2.0206-3.4797-1.4737-4.7876-1.1074-8.082 0.36631-3.2945-0.065-8.7909-4.6445-13.348-4.5795-4.5568-10.08-4.9667-13.373-4.584-3.2926 0.38271-4.5962 0.93678-8.0859-1.0664-3.4897-2.0032-3.6661-3.4032-4.9961-6.4394s-4.449-7.5798-10.693-9.2363c-1.5611-0.41413-3.0428-0.57576-4.4277-0.55273z" style="paint-order:markers fill stroke"/> + <g id="text925" stroke-width=".22458" aria-label="SETUP"> + <path id="path1488" d="m-108.11 191.19q-0.95915 0-2.1639-0.18715v-1.427q1.4095 0.21054 2.1639 0.21054 1.041 0 1.041-1.1112 0-0.30998-0.15206-0.58486-0.14622-0.28072-0.41525-0.386-0.1696-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78955 0 2.164 0.14622v1.4095q-1.4212-0.15207-2.164-0.15207-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25148 0.25733-0.0877 0.15791-0.12867 0.32167-0.0351 0.16376-0.0351 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61995 0.30413 0.38015 0.4211 0.76615t0.11697 0.80125q0 1.1346-0.70183 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1490" d="m-104.26 182.86h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1492" d="m-93.406 182.86v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1494" d="m-92.663 182.86h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67843 0.29242 0.25733 0.70767 0.25733t0.70182-0.25733q0.29243-0.25734 0.38015-0.67843 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52051-1.6376 0.52051t-1.6434-0.52051q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1496" d="m-84.809 184.26v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75445 0-0.44449-0.23979-0.75446-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87142 0.52637 0.66673 0.52637 1.6376 0 0.97085-0.52637 1.6434-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text929" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1499" d="m-75.457 182.86v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1501" d="m-73.223 185.47q-0.08773 0.47958-0.08773 1.5089t0.08773 1.5089q0.10527 0.56731 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36845 0.39185-0.93576 0.08773-0.48542 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.36261-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64919-0.16376-2.0411 0-1.392 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.6141 1.6668-0.6141 1.0176 0 1.6668 0.6141 0.64918 0.60824 0.88312 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.3919-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60824-1.6668 0.60824-1.0176 0-1.6668-0.60824-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1503" d="m-67.24 185.47q-0.08773 0.47958-0.08773 1.5089t0.08773 1.5089q0.10527 0.56731 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36845 0.39185-0.93576 0.08773-0.48542 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.36261-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64919-0.16376-2.0411 0-1.392 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.6141 1.6668-0.6141 1.0176 0 1.6668 0.6141 0.64918 0.60824 0.88312 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.3919-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60824-1.6668 0.60824-1.0176 0-1.6668-0.60824-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1505" d="m-62.374 191.1v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1507" d="m-54.262 191.19q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21054 2.1639 0.21054 1.041 0 1.041-1.1112 0-0.30998-0.15206-0.58486-0.14621-0.28072-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78955 0 2.1639 0.14622v1.4095q-1.4212-0.15207-2.1639-0.15207-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.08773 0.15791-0.12867 0.32167-0.03509 0.16376-0.03509 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61995 0.30412 0.38015 0.42109 0.76615t0.11697 0.80125q0 1.1346-0.70182 1.8247t-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <path id="rect830" d="m-34.068 68.946h61.237c0.87182 0 1.5737 0.70186 1.5737 1.5737v57.404c0 0.87182-0.70186 1.5737-1.5737 1.5737h-61.237c-0.87182 0-1.5737-0.70186-1.5737-1.5737v-57.404c0-0.87182 0.70186-1.5737 1.5737-1.5737z" fill="#336790" style="paint-order:markers fill stroke"/> + <path id="rect935" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m423.13 43.688c-4.7073-0.044694-13.613 0.13281-13.613 0.13281-0.43195 0-0.7793 0.36438-0.7793 0.81445v5.5254h-8.1113v-5.5254c0-0.45012-0.34735-0.81445-0.77929-0.81445h-9.6719c-0.43195 0-0.7793 0.36438-0.7793 0.81445v20.48c0 0.45012 0.34707 0.8125 0.7793 0.8125h9.6719c0.43194 0 0.77929-0.36232 0.77929-0.8125v-5.5254h8.1113v5.5254c0 0.45012 0.34739 0.8125 0.7793 0.8125h4.8945v26.061c-2.8064 1.1139-4.7832 3.8423-4.7832 7.0547v39.494c0 4.2077 3.388 7.5957 7.5957 7.5957s7.5938-3.388 7.5938-7.5957v-39.494c0-3.2125-1.9766-5.9409-4.7832-7.0547v-26.061h5.3008c0.84434-0.74337 1.66-3.7262 6.1699-6.0059 12.111-4.1603 17.37 6.1474 17.277 4.7246-0.09864-1.519-0.77159-11.047-11.346-16.635-4.6068-2.0716-10.023-4.1068-11.484-4.1914-0.15078-0.079455-1.2532-0.11791-2.8223-0.13281z" fill="#e5b62f" stroke="#e5b62f" stroke-width="1.8045" style="paint-order:markers fill stroke"/> + <path id="path943" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m433.72 12.014c-4.1549 0.06908-7.4443 1.7901-9.4394 3.2734-2.6602 1.9777-3.5133 3.1091-7.5371 3.1191-4.0238 0.010205-4.8789-1.1215-7.5488-3.0859-2.6699-1.9645-7.6428-4.3321-13.879-2.6445-6.2361 1.6876-9.3374 6.2423-10.652 9.2852-1.3149 3.0428-1.4871 4.4482-4.9668 6.4688-3.4797 2.0206-4.7875 1.4757-8.082 1.1094-3.2945-0.36631-8.7909 0.065007-13.348 4.6445-4.5568 4.5795-4.9666 10.08-4.584 13.373 0.38259 3.2926 0.93677 4.5962-1.0664 8.0859-2.0032 3.4897-3.4032 3.6661-6.4394 4.9961-3.0363 1.33-7.5798 4.449-9.2363 10.693-1.6566 6.2444 0.74308 11.207 2.7207 13.867 1.9777 2.6602 3.1091 3.5133 3.1191 7.5371 0.00982 4.0238-1.1196 4.8769-3.084 7.5469-1.9645 2.67-4.3321 7.6448-2.6445 13.881 1.6876 6.236 6.2403 9.3374 9.2832 10.652 3.0428 1.3149 4.4501 1.4871 6.4707 4.9668 2.0205 3.4797 1.4757 4.7856 1.1094 8.0801-0.36631 3.2945 0.06278 8.7928 4.6426 13.35 4.5795 4.5568 10.08 4.9549 13.373 4.5723 3.2926-0.38272 4.5962-0.9251 8.0859 1.0781 3.4897 2.0032 3.668 3.4032 4.998 6.4394 1.33 3.0362 4.447 7.5798 10.691 9.2363 6.2444 1.6565 13.901-1.5082 13.867-2.7226-0.0344-1.2144-5.1602 0.87503-10.301-2.3594-5.1405-3.2344-4.7729-5.2312-5.9062-7.8184-1.1333-2.5872-3.1606-7.4448-8.8164-10.691-5.6557-3.2466-10.87-2.5429-13.676-2.2168-2.8057 0.32617-2.9932 0.8948-5.8887-1.9863-2.8955-2.8812-2.318-3.0658-2.0059-5.873 0.31218-2.8073 0.98369-8.0206-2.291-13.66s-8.1377-7.6472-10.73-8.7676c-2.5928-1.1204-3.0365-0.71142-4.1035-4.6543-1.067-3.943-0.48649-3.8284 1.1875-6.1035 1.6739-2.2751 4.8698-6.4494 4.8535-12.971-0.01587-6.5213-3.2327-10.692-4.918-12.959-1.6852-2.2667-2.272-2.1417-1.2246-6.0898 1.0474-3.9482 1.4987-3.5405 4.0859-4.6738 2.5872-1.1333 7.4467-3.1626 10.693-8.8184 3.2466-5.6557 2.5429-10.868 2.2168-13.674-0.32591-2.8057-0.89483-2.9932 1.9863-5.8887 2.8812-2.8955 3.0638-2.3297 5.8711-2.0176 2.8072 0.31211 8.0226 0.99541 13.662-2.2793 5.6395-3.2747 7.6354-8.1376 8.7559-10.73 1.1204-2.5928 0.72114-3.0365 4.6641-4.1035 3.9429-1.067 3.8284-0.48836 6.1035 1.1855 2.2751 1.6739 6.4494 4.8717 12.971 4.8555 6.5213-0.016252 10.682-3.2347 12.949-4.9199 2.2667-1.6852 2.1417-2.2701 6.0898-1.2227 3.9482 1.0474 3.5522 1.4987 4.6856 4.0859 1.1333 2.5872 3.1607 7.4448 8.8164 10.691s10.87 2.5429 13.676 2.2168c2.8057-0.3261 2.9932-0.89287 5.8887 1.9883s2.318 3.0638 2.0059 5.8711c-0.31212 2.8072-0.98369 8.0207 2.291 13.66s8.1376 7.6355 10.73 8.7559c2.5928 1.1204 3.0365 0.72311 4.1035 4.666 1.067 3.9429 0.48641 3.8284-1.1875 6.1035-1.6739 2.2751-4.8697 6.4494-4.8535 12.971 0.01625 6.5213 3.2327 10.681 4.918 12.947 1.6852 2.2667 2.27 2.1436 1.2227 6.0918-1.0474 3.9482-1.4968 3.5503-4.084 4.6836-2.5872 1.1333-7.4448 3.1626-10.691 8.8184-3.2466 5.6557-2.5448 10.868-2.2188 13.674 0.32609 2.8056 0.89482 2.9932-1.9863 5.8887-2.8812 2.8955-3.0638 2.32-5.8711 2.0078-2.8072-0.31219-8.0226-0.9856-13.662 2.2891-5.6395 3.2747-7.6452 8.1376-8.7656 10.73-0.9313 2.1552-0.84174 2.8278-3.0371 3.6055-0.31286-0.1736-0.67424-0.33971-1.1055-0.50195-3.6364-1.3682-4.115 0.48194-7.0996 2.7051-2.684 1.9992-4.605 2.234-4.4922 4.8711-0.25335-0.0254-0.49071-0.03001-0.68164-0.00781-0.60936 0.07067-0.85221 0.17155-1.498-0.19922s-0.67769-0.63142-0.92383-1.1934c-0.24616-0.56187-0.82291-1.4024-1.9785-1.709-1.1557-0.30652-2.5727 0.2791-2.5664 0.50391 0.00642 0.2245 0.95492-0.16129 1.9062 0.4375 0.95133 0.5986 0.88401 0.96652 1.0938 1.4453 0.20965 0.47887 0.58419 1.3796 1.6309 1.9805 1.0467 0.60083 2.012 0.47055 2.5312 0.41016 0.39726-0.04627 0.51372-0.11363 0.78515 0.09375 0.79696 2.7289 2.7246 2.4282 6.0664 3.6855 3.6364 1.3682 4.7478 3.0142 7.7324 0.79102 2.1873-1.6292 1.9673-2.8055 1.4394-4.7266 4.8594-2.0322 7.4092-5.8859 8.5684-8.5684 1.3149-3.0428 1.4871-4.4482 4.9668-6.4688 3.4797-2.0206 4.7876-1.4757 8.082-1.1094 3.2945 0.36624 8.7909-0.06484 13.348-4.6445 4.5568-4.5795 4.9667-10.08 4.584-13.373-0.38271-3.2926-0.93681-4.5962 1.0664-8.0859 2.0032-3.4897 3.4032-3.666 6.4394-4.9961 3.0363-1.33 7.5798-4.449 9.2363-10.693 1.6565-6.2444-0.74299-11.207-2.7207-13.867-1.9777-2.6601-3.1091-3.5133-3.1191-7.5371-0.00983-4.0238 1.1195-4.8769 3.084-7.5469 1.9645-2.6699 4.3321-7.6448 2.6445-13.881-1.6876-6.2361-6.2404-9.3375-9.2832-10.652-3.0428-1.3149-4.4502-1.4852-6.4707-4.9648s-1.4737-4.7876-1.1074-8.082c0.36631-3.2945-0.065-8.7928-4.6445-13.35-4.5795-4.5568-10.08-4.9647-13.373-4.582-3.2926 0.38271-4.5962 0.93681-8.0859-1.0664-3.4897-2.0032-3.6661-3.4032-4.9961-6.4395-1.33-3.0363-4.449-7.5817-10.693-9.2383-1.5611-0.41413-3.0428-0.57381-4.4277-0.55078z" fill="#fff" style="paint-order:markers fill stroke"/> + <g id="text955" fill="#fff" stroke-width=".22458" aria-label="SETUP"> + <path id="path1476" d="m-30.49 126.82q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10528-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25148-1.0995-0.65504-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76615 0.11697 0.38601 0.11697 0.80125 0 1.1346-0.70182 1.8247-0.70182 0.69013-1.8364 0.69013z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1478" d="m-26.636 118.49h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1480" d="m-15.787 118.49v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1482" d="m-15.044 118.49h1.4972v5.2403q0 0.54976 0.04094 0.7486 0.08773 0.4211 0.3743 0.67843 0.29243 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67843 0.04094-0.19884 0.04094-0.7486v-5.2403h1.4972v5.2403q0 0.82463-0.093576 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052-0.95331 0-1.6434-0.52052-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1484" d="m-7.1892 119.89v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52637 0.66673 0.52637 1.6376t-0.52637 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text959" fill="#e5b62f" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1465" d="m2.1625 118.49v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1467" d="m4.3967 121.1q-0.087728 0.47957-0.087728 1.5089t0.087728 1.5089q0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261t0.73691-0.36261q0.28658-0.36846 0.39185-0.93576 0.087728-0.48543 0.087728-1.5089 0-1.0293-0.087728-1.5089-0.10527-0.56731-0.39185-0.92992-0.28073-0.36845-0.73691-0.36845t-0.74276 0.36845q-0.28073 0.36261-0.386 0.92992zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409t1.6668 0.61409q0.64918 0.60824 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825t-1.6668-0.60825q-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1469" d="m10.38 121.1q-0.08773 0.47957-0.08773 1.5089t0.08773 1.5089q0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92992-0.28073-0.36845-0.73691-0.36845-0.45618 0-0.74276 0.36845-0.28073 0.36261-0.386 0.92992zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60824 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1471" d="m15.246 126.73v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1473" d="m23.358 126.82q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10528-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25148-1.0995-0.65504-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76615 0.11697 0.38601 0.11697 0.80125 0 1.1346-0.70182 1.8247-0.70182 0.69013-1.8364 0.69013z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <path id="rect1036" d="m-34.068 133.32h61.237c0.87182 0 1.5737 0.70186 1.5737 1.5737v57.404c0 0.87182-0.70186 1.5737-1.5737 1.5737h-61.237c-0.87182 0-1.5737-0.70186-1.5737-1.5737v-57.404c0-0.87182 0.70186-1.5737 1.5737-1.5737z" style="paint-order:markers fill stroke"/> + <path id="rect1038" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m423.13 286.97c-4.7073-0.0447-13.613 0.13476-13.613 0.13476-0.43195 0-0.7793 0.36236-0.7793 0.8125v5.5274h-8.1113v-5.5274c0-0.4501-0.34735-0.8125-0.77929-0.8125h-9.6719c-0.43195 0-0.7793 0.36236-0.7793 0.8125v20.482c0 0.45015 0.34707 0.81055 0.7793 0.81055h9.6719c0.43194 0 0.77929-0.36052 0.77929-0.81055v-5.5273h8.1113v5.5273c0 0.45015 0.34739 0.81055 0.7793 0.81055h4.8945v26.061c-2.8064 1.1139-4.7832 3.8423-4.7832 7.0547v39.496c0 4.2077 3.388 7.5938 7.5957 7.5938s7.5938-3.386 7.5938-7.5938v-39.496c0-3.2125-1.9766-5.9409-4.7832-7.0547v-26.061h5.3008c0.84434-0.74336 1.66-3.7243 6.1699-6.0039 12.111-4.1603 17.37 6.1455 17.277 4.7227-0.09864-1.519-0.77159-11.045-11.346-16.633-4.6068-2.0716-10.023-4.1068-11.484-4.1914-0.15078-0.07946-1.2532-0.11986-2.8223-0.13476z" fill="#fff" stroke="#fff" stroke-width="1.8045" style="paint-order:markers fill stroke"/> + <path id="path1046" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m433.72 255.3c-4.1549 0.06908-7.4443 1.7902-9.4394 3.2734-2.6602 1.9777-3.5133 3.1091-7.5371 3.1191-4.0238 0.01133-4.8789-1.1195-7.5488-3.084-2.6699-1.9645-7.6428-4.3321-13.879-2.6445s-9.3374 6.2404-10.652 9.2832c-1.3149 3.0428-1.4871 4.4502-4.9668 6.4707-3.4797 2.0206-4.7875 1.4737-8.082 1.1074-3.2945-0.36624-8.7909 0.06484-13.348 4.6445-4.5568 4.5795-4.9666 10.08-4.584 13.373 0.38259 3.2926 0.93677 4.5962-1.0664 8.0859-2.0032 3.4897-3.4032 3.6661-6.4394 4.9961-3.0363 1.33-7.5798 4.449-9.2363 10.693-1.6566 6.2444 0.74308 11.207 2.7207 13.867 1.9777 2.6601 3.1091 3.5133 3.1191 7.5371 0.00982 4.0238-1.1196 4.8789-3.084 7.5488-1.9645 2.67-4.3321 7.6428-2.6445 13.879 1.6876 6.236 6.2403 9.3374 9.2832 10.652 3.0428 1.3149 4.4501 1.4871 6.4707 4.9668 2.0205 3.4797 1.4757 4.7875 1.1094 8.082-0.36631 3.2945 0.06278 8.7909 4.6426 13.348 4.5795 4.5568 10.08 4.9549 13.373 4.5723 3.2926-0.38271 4.5962-0.9251 8.0859 1.0781 3.4897 2.0032 3.668 3.4032 4.998 6.4394 1.33 3.0362 4.447 7.5798 10.691 9.2363 6.2444 1.6565 13.901-1.5063 13.867-2.7207-0.0344-1.2144-5.1602 0.87307-10.301-2.3613-5.1405-3.2344-4.7729-5.2312-5.9062-7.8184-1.1333-2.5872-3.1606-7.4448-8.8164-10.691-5.6557-3.2466-10.87-2.5429-13.676-2.2168-2.8057 0.32618-2.9932 0.89481-5.8887-1.9863-2.8955-2.8812-2.318-3.0638-2.0059-5.8711 0.31218-2.8073 0.98369-8.0226-2.291-13.662-3.2747-5.6395-8.1377-7.6452-10.73-8.7656-2.5928-1.1204-3.0365-0.71142-4.1035-4.6543-1.067-3.943-0.48649-3.8303 1.1875-6.1055 1.6739-2.2751 4.8698-6.4494 4.8535-12.971-0.01587-6.5214-3.2327-10.69-4.918-12.957-1.6852-2.2667-2.272-2.1436-1.2246-6.0918 1.0474-3.9482 1.4987-3.5405 4.0859-4.6738 2.5872-1.1333 7.4467-3.1607 10.693-8.8164 3.2466-5.6558 2.5429-10.87 2.2168-13.676-0.32591-2.8057-0.89483-2.9931 1.9863-5.8887 2.8812-2.8955 3.0638-2.3297 5.8711-2.0176 2.8072 0.31219 8.0226 0.9954 13.662-2.2793s7.6354-8.1377 8.7559-10.73c1.1204-2.5928 0.72114-3.0365 4.6641-4.1035 3.9429-1.067 3.8284-0.48641 6.1035 1.1875 2.2751 1.6739 6.4494 4.8698 12.971 4.8535 6.5213-0.01512 10.682-3.2327 12.949-4.918 2.2667-1.6852 2.1417-2.2701 6.0898-1.2226 3.9482 1.0474 3.5522 1.4967 4.6856 4.084 1.1333 2.5872 3.1607 7.4448 8.8164 10.691 5.6557 3.2466 10.87 2.5448 13.676 2.2188 2.8057-0.32618 2.9932-0.89485 5.8887 1.9863 2.8955 2.8811 2.318 3.0638 2.0059 5.8711-0.31212 2.8072-0.98369 8.0207 2.291 13.66 3.2747 5.6395 8.1376 7.6354 10.73 8.7559 2.5928 1.1204 3.0365 0.7231 4.1035 4.666 1.067 3.9429 0.48641 3.8284-1.1875 6.1035-1.6739 2.2751-4.8697 6.4494-4.8535 12.971 0.01625 6.5213 3.2327 10.682 4.918 12.949 1.6852 2.2667 2.27 2.1417 1.2227 6.0898-1.0474 3.9482-1.4968 3.5522-4.084 4.6856-2.5872 1.1333-7.4448 3.1607-10.691 8.8164-3.2466 5.6557-2.5448 10.868-2.2188 13.674 0.32609 2.8057 0.89482 2.9932-1.9863 5.8887-2.8812 2.8955-3.0638 2.32-5.8711 2.0078-2.8072-0.31219-8.0226-0.98365-13.662 2.291-5.6395 3.2747-7.6452 8.1376-8.7656 10.73-0.93126 2.1551-0.84199 2.8259-3.0371 3.6035-0.31271-0.17348-0.67455-0.33983-1.1055-0.50196-3.6364-1.3681-4.115 0.48194-7.0996 2.7051-2.684 1.9992-4.605 2.234-4.4922 4.8711-0.25326-0.02538-0.49076-0.03-0.68164-0.00782-0.60936 0.07068-0.85221 0.17156-1.498-0.19922-0.64583-0.37077-0.67769-0.62946-0.92383-1.1914-0.24616-0.56187-0.82291-1.4044-1.9785-1.7109-1.1557-0.30652-2.5727 0.2791-2.5664 0.50391 0.00642 0.2245 0.95492-0.16129 1.9062 0.4375 0.95133 0.5986 0.88401 0.96847 1.0938 1.4473 0.20965 0.47887 0.58419 1.3777 1.6309 1.9785 1.0467 0.60083 2.012 0.47055 2.5312 0.41015 0.39726-0.04626 0.51372-0.11362 0.78515 0.09375 0.79696 2.7289 2.7246 2.4282 6.0664 3.6856 3.6364 1.3682 4.7478 3.0142 7.7324 0.79102 2.1872-1.6292 1.9673-2.8037 1.4394-4.7246 4.8594-2.0322 7.4092-5.8859 8.5684-8.5684 1.3149-3.0428 1.4871-4.4502 4.9668-6.4707 3.4797-2.0206 4.7876-1.4757 8.082-1.1094 3.2945 0.36624 8.7909-0.06289 13.348-4.6426 4.5568-4.5795 4.9667-10.08 4.584-13.373-0.38271-3.2926-0.93681-4.5962 1.0664-8.0859 2.0032-3.4897 3.4032-3.668 6.4394-4.998 3.0363-1.33 7.5798-4.447 9.2363-10.691 1.6565-6.2444-0.74299-11.207-2.7207-13.867-1.9777-2.6602-3.1091-3.5133-3.1191-7.5371-0.00983-4.0238 1.1195-4.8789 3.084-7.5488 1.9645-2.6699 4.3321-7.6448 2.6445-13.881-1.6876-6.236-6.2404-9.3355-9.2832-10.65-3.0428-1.3149-4.4502-1.4871-6.4707-4.9668-2.0206-3.4797-1.4737-4.7876-1.1074-8.082 0.36631-3.2945-0.065-8.7909-4.6445-13.348-4.5795-4.5568-10.08-4.9667-13.373-4.584-3.2926 0.38271-4.5962 0.93682-8.0859-1.0664-3.4897-2.0032-3.6661-3.4032-4.9961-6.4394-1.33-3.0362-4.449-7.5798-10.693-9.2363-1.5611-0.41413-3.0428-0.57576-4.4277-0.55273z" fill="#fff" style="paint-order:markers fill stroke"/> + <g id="text1058" fill="#fff" stroke-width=".22458" aria-label="SETUP"> + <path id="path1450" d="m-30.49 191.19q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21054 2.1639 0.21054 1.041 0 1.041-1.1112 0-0.30998-0.15206-0.58486-0.14621-0.28072-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78955 0 2.1639 0.14622v1.4095q-1.4212-0.15207-2.1639-0.15207-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.08773 0.15791-0.12867 0.32167-0.03509 0.16376-0.03509 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61995 0.30412 0.38015 0.42109 0.76615t0.11697 0.80125q0 1.1346-0.70182 1.8247t-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1452" d="m-26.636 182.86h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1454" d="m-15.787 182.86v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1456" d="m-15.044 182.86h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67843 0.29243 0.25733 0.70767 0.25733t0.70182-0.25733q0.29242-0.25734 0.38015-0.67843 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.093576 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52051-1.6376 0.52051-0.95331 0-1.6434-0.52051-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1458" d="m-7.1892 184.26v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75445 0-0.44449-0.23979-0.75446-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87142 0.52637 0.66673 0.52637 1.6376 0 0.97085-0.52637 1.6434-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1062" fill="#fff" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1439" d="m2.1625 182.86v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1441" d="m4.3967 185.47q-0.087728 0.47958-0.087728 1.5089t0.087728 1.5089q0.10527 0.56731 0.386 0.93576 0.28658 0.36261 0.74276 0.36261t0.73691-0.36261q0.28658-0.36845 0.39185-0.93576 0.087728-0.48542 0.087728-1.5089 0-1.0293-0.087728-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846t-0.74276 0.36846q-0.28073 0.36261-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64919-0.16376-2.0411 0-1.392 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.6141 1.6668-0.6141t1.6668 0.6141q0.64918 0.60824 0.88312 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.3919-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60824-1.6668 0.60824t-1.6668-0.60824q-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1443" d="m10.38 185.47q-0.08773 0.47958-0.08773 1.5089t0.08773 1.5089q0.10527 0.56731 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36845 0.39185-0.93576 0.08773-0.48542 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.36261-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64919-0.16376-2.0411 0-1.392 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64918-0.6141 1.6668-0.6141 1.0176 0 1.6668 0.6141 0.64918 0.60824 0.88312 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.3919-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60824-1.6668 0.60824-1.0176 0-1.6668-0.60824-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1445" d="m15.246 191.1v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1447" d="m23.358 191.19q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21054 2.1639 0.21054 1.041 0 1.041-1.1112 0-0.30998-0.15206-0.58486-0.14621-0.28072-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78955 0 2.1639 0.14622v1.4095q-1.4212-0.15207-2.1639-0.15207-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.08773 0.15791-0.12867 0.32167-0.03509 0.16376-0.03509 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61995 0.30412 0.38015 0.42109 0.76615t0.11697 0.80125q0 1.1346-0.70182 1.8247t-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <path id="rect830-6-9" d="m45.345 70.722h82.571c0.28796 0 0.51978 0.23182 0.51978 0.51978v22.171c0 0.28796-0.23182 0.51978-0.51978 0.51978h-82.571c-0.28796 0-0.51978-0.23182-0.51978-0.51978v-22.171c0-0.28796 0.23182-0.51978 0.51978-0.51978z" fill="#fff" style="paint-order:markers fill stroke"/> + <path id="rect1070" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m645.59 29.135c-2.1498-0.02041-6.2168 0.060546-6.2168 0.060546-0.19725 0-0.35547 0.16556-0.35547 0.37109v2.5234h-3.7051v-2.5234c0-0.20557-0.15821-0.37109-0.35547-0.37109h-4.416c-0.19725 0-0.35742 0.16556-0.35742 0.37109v9.3535c0 0.20557 0.16001 0.37109 0.35742 0.37109h4.416c0.19726 0 0.35547-0.16549 0.35547-0.37109v-2.5234h3.7051v2.5234c0 0.20557 0.15825 0.37109 0.35547 0.37109h2.2363v11.906c-1.2817 0.50868-2.1856 1.7497-2.1856 3.2168v18.037c0 1.9217 1.5471 3.4688 3.4688 3.4688s3.4688-1.5471 3.4688-3.4688v-18.037c0-1.4664-0.90281-2.7077-2.1836-3.2168v-11.906h2.4199c0.38561-0.33948 0.75677-1.7011 2.8164-2.7422 5.5309-1.9 7.9328 2.808 7.8906 2.1582-0.04505-0.69374-0.35053-5.0458-5.1797-7.5977-2.1039-0.94608-4.5788-1.8754-5.2461-1.9141-0.06886-0.036283-0.57246-0.053743-1.2891-0.060546z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".82412" style="paint-order:markers fill stroke"/> + <path id="path1078" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m650.43 14.668c-1.8975 0.031546-3.3994 0.81867-4.3105 1.4961-1.2149 0.90321-1.6057 1.4193-3.4434 1.4238-1.8376 0.004535-2.2279-0.51103-3.4473-1.4082-1.2194-0.89717-3.4899-1.9797-6.3379-1.209-2.848 0.77071-4.2647 2.8506-4.8652 4.2402-0.60051 1.3896-0.67842 2.0323-2.2676 2.9551-1.5892 0.92278-2.1868 0.67314-3.6914 0.50586-1.5046-0.16728-4.0146 0.029711-6.0957 2.1211-2.0811 2.0914-2.2685 4.6037-2.0938 6.1074 0.17473 1.5037 0.42851 2.0996-0.48633 3.6934-0.91487 1.5937-1.5548 1.6738-2.9414 2.2812-1.3867 0.60742-3.4622 2.033-4.2188 4.8848-0.75654 2.8518 0.34098 5.1172 1.2441 6.332 0.90319 1.2149 1.4192 1.6057 1.4238 3.4434 0.00454 1.8377-0.51104 2.2279-1.4082 3.4473-0.89718 1.2194-1.9797 3.4899-1.209 6.3379 0.77071 2.848 2.8506 4.2647 4.2402 4.8652 1.3896 0.60051 2.0323 0.67843 2.9551 2.2676 0.92276 1.5892 0.67316 2.1868 0.50586 3.6914-0.16728 1.5046 0.0297 4.0146 2.1211 6.0957 2.0915 2.0811 4.6037 2.2627 6.1074 2.0879s2.0996-0.42268 3.6934 0.49219c1.5937 0.91486 1.6738 1.5547 2.2812 2.9414 0.60742 1.3866 2.031 3.4622 4.8828 4.2188 2.8518 0.75653 6.3494-0.68953 6.334-1.2441-0.01587-0.55461-2.3574 0.40097-4.7051-1.0762-2.3477-1.4771-2.1797-2.3907-2.6973-3.5723-0.51759-1.1816-1.4424-3.3982-4.0254-4.8809-2.5829-1.4827-4.9648-1.1626-6.2461-1.0137-1.2813 0.14895-1.3671 0.4076-2.6894-0.9082-1.3224-1.3158-1.0586-1.3996-0.91602-2.6816 0.14257-1.2821 0.44867-3.6627-1.0469-6.2383-1.4956-2.5755-3.7163-3.4922-4.9004-4.0039-1.1841-0.5117-1.3857-0.3243-1.873-2.125-0.4873-1.8007-0.22347-1.7481 0.54102-2.7871 0.76447-1.039 2.2242-2.9456 2.2168-5.9238-0.00718-2.9783-1.4764-4.8828-2.2461-5.918-0.76963-1.0352-1.037-0.98009-0.55859-2.7832 0.47833-1.8031 0.68366-1.6152 1.8652-2.1328 1.1816-0.51758 3.4001-1.4444 4.8828-4.0273 1.4827-2.583 1.1626-4.9648 1.0137-6.2461-0.14883-1.2813-0.4076-1.3671 0.90821-2.6895 1.3158-1.3224 1.3976-1.0625 2.6797-0.91992 1.282 0.14253 3.6647 0.45453 6.2402-1.041 2.5755-1.4955 3.4864-3.7163 3.998-4.9004 0.5117-1.1841 0.33013-1.3877 2.1309-1.875 1.8007-0.48731 1.7481-0.22346 2.7871 0.54102 1.039 0.76448 2.9456 2.2262 5.9238 2.2188 2.9783-0.007559 4.8789-1.4784 5.9141-2.248 1.0352-0.76964 0.97813-1.0369 2.7812-0.55859 1.8031 0.47834 1.6211 0.68562 2.1387 1.8672s1.4444 3.4001 4.0273 4.8828c2.583 1.4827 4.9648 1.1607 6.2461 1.0117 1.2813-0.14891 1.3651-0.40761 2.6875 0.9082 1.3224 1.3158 1.0605 1.3996 0.91796 2.6816-0.14252 1.282-0.45062 3.6627 1.0449 6.2383 1.4955 2.5755 3.7162 3.4864 4.9004 3.998 1.1841 0.5117 1.3877 0.33017 1.875 2.1309 0.4873 1.8007 0.22346 1.75-0.54102 2.7891-0.76448 1.039-2.2262 2.9436-2.2188 5.9219 0.00756 2.9783 1.4765 4.8789 2.2461 5.9141 0.76965 1.0352 1.0369 0.97814 0.5586 2.7812-0.47834 1.8031-0.68366 1.623-1.8652 2.1406-1.1816 0.51757-3.4001 1.4424-4.8828 4.0254-1.4827 2.5829-1.1606 4.9647-1.0117 6.2461 0.14892 1.2813 0.40761 1.3671-0.9082 2.6895-1.3158 1.3224-1.3996 1.0586-2.6816 0.91602-1.2821-0.14256-3.6627-0.44865-6.2383 1.0469-2.5756 1.4956-3.4922 3.7163-4.0039 4.9004-0.42128 0.9749-0.43101 1.2878-1.4043 1.6387-0.13992-0.076625-0.29747-0.15087-0.48828-0.22266-1.6607-0.62483-1.8791 0.22103-3.2422 1.2363-1.2238 0.91157-2.0954 1.0256-2.0469 2.2246-0.11719-0.012065-0.22826-0.014151-0.3164-0.003906-0.27829 0.032126-0.38865 0.077526-0.6836-0.091797s-0.30944-0.28632-0.42187-0.54297c-0.11241-0.25659-0.3746-0.64124-0.90235-0.78125-0.52779-0.13999-1.1767 0.12778-1.1738 0.23047 0.00294 0.10254 0.43663-0.07423 0.8711 0.19922 0.43447 0.27337 0.40421 0.4415 0.5 0.66016 0.09573 0.21868 0.26613 0.6299 0.74414 0.9043 0.47801 0.27439 0.91911 0.21509 1.1562 0.1875 0.17999-0.020943 0.25507-0.013849 0.37695 0.078125 0.37226 1.1966 1.2449 1.0814 2.752 1.6484 1.6608 0.62483 2.1701 1.3747 3.5332 0.35938 0.9978-0.74322 0.89282-1.2826 0.65234-2.1582 2.2207-0.92784 3.3884-2.6867 3.918-3.9121 0.60051-1.3896 0.67842-2.0323 2.2676-2.9551 1.5892-0.92279 2.1868-0.67315 3.6914-0.50586 1.5046 0.16724 4.0146-0.029704 6.0957-2.1211 2.0811-2.0914 2.2685-4.6037 2.0938-6.1074-0.17477-1.5037-0.42853-2.0996 0.48633-3.6934 0.91486-1.5937 1.5548-1.6738 2.9414-2.2812 1.3866-0.60742 3.4622-2.031 4.2188-4.8828 0.75654-2.8518-0.34091-5.1191-1.2441-6.334-0.90322-1.2149-1.4193-1.6038-1.4238-3.4414-0.00453-1.8376 0.51104-2.2279 1.4082-3.4473 0.89716-1.2194 1.9797-3.4919 1.209-6.3398-0.77071-2.848-2.8506-4.2647-4.2402-4.8652-1.3896-0.60051-2.0323-0.67842-2.9551-2.2676-0.92278-1.5892-0.67315-2.1868-0.50586-3.6914 0.16728-1.5046-0.02971-4.0146-2.1211-6.0957-2.0914-2.0811-4.6037-2.2685-6.1074-2.0938-1.5037 0.17477-2.0996 0.42853-3.6934-0.48633-1.5937-0.91486-1.6738-1.5548-2.2812-2.9414-0.60741-1.3866-2.033-3.4622-4.8848-4.2188-0.71295-0.18913-1.389-0.26247-2.0215-0.25195z" fill="#336790" style="paint-order:markers fill stroke"/> + <g id="text1090" fill="#336790" stroke-width=".22458" aria-label="SETUP"> + <path id="path1424" d="m70.306 86.538q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.06433-0.46788-0.10527-0.29827-0.04094-0.61409-0.11697-0.30997-0.08188-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.09942-0.16376 0.09943-0.25149 0.25733-0.08773 0.15791-0.12867 0.32167-0.03509 0.16376-0.03509 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.07018 0.69012 0.15791 0.54391 0.08188 0.87728 0.25733 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247t-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1426" d="m74.16 78.209h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1428" d="m85.009 78.209v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1430" d="m85.752 78.209h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67843 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29243-0.25733 0.38015-0.67843 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052-0.95331 0-1.6434-0.52052-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1432" d="m93.607 79.613v2.3862h0.36261q0.50297 0 0.73106-0.04679 0.3977-0.08188 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.04679-0.73106-0.04679zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.08773 0.83049 0.19885 1.351 0.87143 0.52637 0.66673 0.52637 1.6376t-0.52637 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.08773-1.234 0.08773h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1094" fill="#e5b62f" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1413" d="m102.96 78.209v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1415" d="m105.19 80.818q-0.0877 0.47958-0.0877 1.5089t0.0877 1.5089q0.10528 0.5673 0.38601 0.93576 0.28657 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.0877-0.48543 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45619 0-0.74276 0.36846-0.28073 0.36261-0.38601 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411t0.16376-2.0411q0.23394-0.94746 0.88312-1.5557 0.64919-0.61409 1.6668-0.61409t1.6668 0.61409q0.64919 0.60824 0.88313 1.5557 0.16375 0.64918 0.16375 2.0411t-0.16375 2.0411q-0.23394 0.94746-0.88313 1.5616-0.64918 0.60824-1.6668 0.60824t-1.6668-0.60824q-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1417" d="m111.18 80.818q-0.0877 0.47958-0.0877 1.5089t0.0877 1.5089q0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261t0.73691-0.36261q0.28658-0.36846 0.39185-0.93576 0.0877-0.48543 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846t-0.74276 0.36846q-0.28073 0.36261-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411t0.16376-2.0411q0.23394-0.94746 0.88313-1.5557 0.64918-0.61409 1.6668-0.61409t1.6668 0.61409q0.64919 0.60824 0.88313 1.5557 0.16376 0.64918 0.16376 2.0411t-0.16376 2.0411q-0.23394 0.94746-0.88313 1.5616-0.64918 0.60824-1.6668 0.60824t-1.6668-0.60824q-0.64919-0.61409-0.88313-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1419" d="m116.04 86.444v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1421" d="m124.15 86.538q-0.95916 0-2.164-0.18715v-1.427q1.4095 0.21055 2.164 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.06433-0.46789-0.10527-0.29827-0.04094-0.61409-0.11697-0.30997-0.08188-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78954 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22225 0-0.39185 0.09942-0.16376 0.09943-0.25149 0.25733-0.0877 0.15791-0.12867 0.32167-0.0351 0.16376-0.0351 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.07018 0.69013 0.15791 0.54391 0.08188 0.87727 0.25733 0.46788 0.23979 0.77201 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247t-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <path id="rect830-6" d="m45.345 102.91h82.571c0.28796 0 0.51978 0.23183 0.51978 0.51978v22.171c0 0.28796-0.23182 0.51978-0.51978 0.51978h-82.571c-0.28796 0-0.51978-0.23182-0.51978-0.51978v-22.171c0-0.28795 0.23182-0.51978 0.51978-0.51978z" fill="#336790" style="paint-order:markers fill stroke"/> + <path id="rect1168" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m645.59 150.78c-2.1498-0.02041-6.2168 0.06055-6.2168 0.06055-0.19725 0-0.35547 0.16549-0.35547 0.37109v2.5254h-3.7051v-2.5254c0-0.2056-0.15821-0.37109-0.35547-0.37109h-4.416c-0.19725 0-0.35742 0.16549-0.35742 0.37109v9.3535c0 0.20561 0.16001 0.37109 0.35742 0.37109h4.416c0.19726 0 0.35547-0.16548 0.35547-0.37109v-2.5234h3.7051v2.5234c0 0.20561 0.15825 0.37109 0.35547 0.37109h2.2363v11.906c-1.2817 0.50867-2.1856 1.7516-2.1856 3.2188v18.037c0 1.9216 1.5471 3.4688 3.4688 3.4688s3.4688-1.5471 3.4688-3.4688v-18.037c0-1.4665-0.90278-2.7096-2.1836-3.2188v-11.906h2.4199c0.38561-0.3394 0.75677-1.7011 2.8164-2.7422 5.5309-1.9 7.9328 2.808 7.8906 2.1582-0.04505-0.69373-0.35053-5.0458-5.1797-7.5977-2.1039-0.94609-4.5788-1.8754-5.2461-1.9141-0.06886-0.03628-0.57246-0.05374-1.2891-0.06055z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".82412" style="paint-order:markers fill stroke"/> + <path id="path1176" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m650.43 136.31c-1.8975 0.03152-3.3994 0.81663-4.3105 1.4941-1.2149 0.90323-1.6057 1.4193-3.4434 1.4238-1.8376 0.00378-2.2279-0.51106-3.4473-1.4082-1.2194-0.89719-3.4899-1.9778-6.3379-1.207-2.848 0.77069-4.2647 2.8506-4.8652 4.2402-0.60051 1.3896-0.67842 2.0304-2.2676 2.9531-1.5892 0.92281-2.1868 0.6751-3.6914 0.50782-1.5046-0.16744-4.0146 0.02853-6.0957 2.1191-2.0811 2.0914-2.2685 4.6056-2.0938 6.1094 0.17473 1.5038 0.42851 2.0977-0.48633 3.6914-0.91487 1.5937-1.5548 1.6758-2.9414 2.2832-1.3867 0.60741-3.4622 2.031-4.2188 4.8828-0.75654 2.8518 0.34098 5.1171 1.2441 6.332 0.90319 1.2149 1.4192 1.6057 1.4238 3.4434 0.00454 1.8376-0.51104 2.2279-1.4082 3.4473-0.89718 1.2194-1.9797 3.4899-1.209 6.3379 0.77071 2.848 2.8506 4.2647 4.2402 4.8652 1.3896 0.6005 2.0323 0.67844 2.9551 2.2676 0.92276 1.5892 0.67316 2.1868 0.50586 3.6914-0.16728 1.5046 0.0297 4.0146 2.1211 6.0957 2.0915 2.081 4.6037 2.2627 6.1074 2.0879 1.5037-0.17499 2.0996-0.42268 3.6934 0.49219 1.5937 0.91484 1.6738 1.5548 2.2812 2.9414 0.60742 1.3866 2.031 3.4622 4.8828 4.2188 2.8518 0.75654 6.3494-0.68758 6.334-1.2422-0.01587-0.55461-2.3574 0.39899-4.7051-1.0781-2.3477-1.4772-2.1797-2.3888-2.6973-3.5703-0.51759-1.1816-1.4424-3.4001-4.0254-4.8828-2.5829-1.4827-4.9648-1.1626-6.2461-1.0137-1.2813 0.14891-1.3671 0.40955-2.6894-0.90625-1.3224-1.3158-1.0586-1.3996-0.91602-2.6816 0.14257-1.2821 0.44867-3.6647-1.0469-6.2402-1.4956-2.5756-3.7163-3.4922-4.9004-4.0039-1.1841-0.51171-1.3857-0.32447-1.873-2.125-0.4873-1.8008-0.22347-1.7481 0.54102-2.7871 0.76447-1.039 2.2242-2.9456 2.2168-5.9238-0.00718-2.9783-1.4764-4.8828-2.2461-5.918-0.76963-1.0352-1.037-0.97811-0.55859-2.7812 0.47833-1.8031 0.68366-1.6172 1.8652-2.1348 1.1816-0.51756 3.4001-1.4444 4.8828-4.0273 1.4827-2.583 1.1626-4.9628 1.0137-6.2441-0.14883-1.2813-0.4076-1.3671 0.90821-2.6894s1.3976-1.0644 2.6797-0.92188c1.282 0.14249 3.6647 0.45455 6.2402-1.041 2.5755-1.4955 3.4864-3.7163 3.998-4.9004 0.5117-1.1842 0.33013-1.3877 2.1309-1.875 1.8007-0.48734 1.7481-0.22152 2.7871 0.54296 1.039 0.76449 2.9456 2.2242 5.9238 2.2168 2.9783-0.00756 4.8789-1.4765 5.9141-2.2461 1.0352-0.76967 0.97813-1.0369 2.7812-0.5586 1.8031 0.47834 1.6211 0.68368 2.1387 1.8652 0.51758 1.1816 1.4444 3.4001 4.0273 4.8828s4.9648 1.1607 6.2461 1.0117c1.2813-0.14891 1.3651-0.4076 2.6875 0.9082 1.3224 1.3158 1.0605 1.3996 0.91796 2.6816-0.14252 1.2821-0.45062 3.6627 1.0449 6.2383 1.4955 2.5755 3.7162 3.4883 4.9004 4 1.1841 0.51171 1.3877 0.32819 1.875 2.1289 0.4873 1.8007 0.22346 1.7501-0.54102 2.7891-0.76448 1.039-2.2262 2.9456-2.2188 5.9238 0.00756 2.9783 1.4765 4.8769 2.2461 5.9121 0.76965 1.0352 1.0369 0.97811 0.5586 2.7812-0.47834 1.8031-0.68366 1.6231-1.8652 2.1406-1.1816 0.51756-3.4001 1.4444-4.8828 4.0273-1.4827 2.583-1.1606 4.9628-1.0117 6.2441s0.40761 1.3671-0.9082 2.6894-1.3996 1.0585-2.6816 0.91602c-1.2821-0.14249-3.6627-0.44865-6.2383 1.0469-2.5756 1.4956-3.4922 3.7163-4.0039 4.9004-0.42101 0.9743-0.43101 1.288-1.4023 1.6387-0.14024-0.0769-0.29879-0.15063-0.49024-0.22266-1.6607-0.62483-1.8791 0.22103-3.2422 1.2363-1.2238 0.91157-2.0954 1.0256-2.0469 2.2246-0.11719-0.01206-0.22826-0.01416-0.3164-0.00391-0.27829 0.03402-0.38865 0.07753-0.6836-0.0918-0.29495-0.16932-0.30944-0.28633-0.42187-0.54296-0.11241-0.25663-0.3746-0.64126-0.90235-0.78125-0.52779-0.13985-1.1767 0.12766-1.1738 0.23046 0.00294 0.10243 0.43663-0.07441 0.8711 0.19922 0.43447 0.27326 0.40421 0.44148 0.5 0.66016 0.09573 0.21883 0.26613 0.62986 0.74414 0.9043 0.47801 0.27439 0.91911 0.21509 1.1562 0.1875 0.17999-0.02009 0.25507-0.01352 0.37695 0.07812 0.37226 1.1966 1.2449 1.0814 2.752 1.6484 1.6608 0.62483 2.1701 1.3747 3.5332 0.35937 0.99763-0.74309 0.89468-1.2829 0.65429-2.1582 2.2192-0.92808 3.3866-2.687 3.916-3.9121 0.60051-1.3897 0.67842-2.0323 2.2676-2.9551s2.1868-0.67314 3.6914-0.50586c1.5046 0.16744 4.0146-0.03044 6.0957-2.1211 2.0811-2.0914 2.2685-4.6037 2.0938-6.1074s-0.42853-2.0996 0.48633-3.6934c0.91486-1.5938 1.5548-1.6738 2.9414-2.2812 1.3866-0.60741 3.4622-2.031 4.2188-4.8828 0.75654-2.8518-0.34091-5.1191-1.2441-6.334-0.90322-1.2149-1.4193-1.6038-1.4238-3.4414-0.00453-1.8376 0.51104-2.2279 1.4082-3.4473 0.89716-1.2194 1.9797-3.4919 1.209-6.3398-0.77071-2.848-2.8506-4.2628-4.2402-4.8633-1.3896-0.60053-2.0323-0.68036-2.9551-2.2695-0.92278-1.5891-0.67315-2.1849-0.50586-3.6894 0.16728-1.5046-0.02971-4.0166-2.1211-6.0977-2.0914-2.0811-4.6037-2.2666-6.1074-2.0918-1.5037 0.17499-2.0996 0.42659-3.6934-0.48828-1.5937-0.91488-1.6738-1.5548-2.2812-2.9414-0.60741-1.3867-2.033-3.4602-4.8848-4.2168-0.71295-0.18912-1.389-0.26246-2.0215-0.25195z" fill="#fff" style="paint-order:markers fill stroke"/> + <g id="text1188" fill="#fff" stroke-width=".22458" aria-label="SETUP"> + <path id="path1385" d="m70.306 118.72q-0.95916 0-2.1639-0.18716v-1.427q1.4095 0.21054 2.1639 0.21054 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10528-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25148-1.0995-0.65504-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78955 0 2.1639 0.14622v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32166-0.03509 0.16376-0.03509 0.32167 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23978 0.772 0.61994 0.30412 0.38015 0.42109 0.76615 0.11697 0.386 0.11697 0.80125 0 1.1346-0.70182 1.8247-0.70182 0.69013-1.8364 0.69013z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1387" d="m74.16 110.39h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1389" d="m85.009 110.39v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1391" d="m85.752 110.39h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.4211 0.3743 0.67843 0.29242 0.25733 0.70767 0.25733t0.70182-0.25733q0.29243-0.25733 0.38015-0.67843 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052-0.95331 0-1.6434-0.52052-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1393" d="m93.607 111.8v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52637 0.66673 0.52637 1.6376t-0.52637 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1192" fill="#e5b62f" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1396" d="m102.96 110.39v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1398" d="m105.19 113q-0.0877 0.47957-0.0877 1.5089t0.0877 1.5089q0.10528 0.5673 0.38601 0.93576 0.28657 0.3626 0.74276 0.3626 0.45618 0 0.73691-0.3626 0.28658-0.36846 0.39185-0.93576 0.0877-0.48543 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.56731-0.39185-0.92992-0.28073-0.36845-0.73691-0.36845-0.45619 0-0.74276 0.36845-0.28073 0.36261-0.38601 0.92992zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64919-0.6141 1.6668-0.6141t1.6668 0.6141q0.64919 0.60824 0.88313 1.5557 0.16375 0.64919 0.16375 2.0411 0 1.392-0.16375 2.0411-0.23394 0.94746-0.88313 1.5616-0.64918 0.60825-1.6668 0.60825t-1.6668-0.60825q-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1400" d="m111.18 113q-0.0877 0.47957-0.0877 1.5089t0.0877 1.5089q0.10527 0.5673 0.386 0.93576 0.28658 0.3626 0.74276 0.3626t0.73691-0.3626q0.28658-0.36846 0.39185-0.93576 0.0877-0.48543 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.56731-0.39185-0.92992-0.28073-0.36845-0.73691-0.36845t-0.74276 0.36845q-0.28073 0.36261-0.386 0.92992zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88313-1.5557 0.64918-0.6141 1.6668-0.6141t1.6668 0.6141q0.64919 0.60824 0.88313 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88313 1.5616-0.64918 0.60825-1.6668 0.60825t-1.6668-0.60825q-0.64919-0.61409-0.88313-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1402" d="m116.04 118.63v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1404" d="m124.15 118.72q-0.95916 0-2.164-0.18716v-1.427q1.4095 0.21054 2.164 0.21054 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46789-0.10528-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25148-1.0995-0.65504-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78954 0 2.1639 0.14622v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22225 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.0877 0.15791-0.12867 0.32166-0.0351 0.16376-0.0351 0.32167 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69013 0.15791 0.54391 0.0819 0.87727 0.25734 0.46788 0.23978 0.77201 0.61994 0.30412 0.38015 0.42109 0.76615t0.11697 0.80125q0 1.1346-0.70182 1.8247-0.70182 0.69013-1.8364 0.69013z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <path id="rect830-6-9-8" d="m45.345 135.09h82.571c0.28796 0 0.51978 0.23182 0.51978 0.51978v22.171c0 0.28796-0.23182 0.51978-0.51978 0.51978h-82.571c-0.28796 0-0.51978-0.23182-0.51978-0.51978v-22.171c0-0.28796 0.23182-0.51978 0.51978-0.51978z" fill="#fff" style="paint-order:markers fill stroke"/> + <path id="rect1222" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m645.59 272.42c-2.1498-0.02041-6.2168 0.06055-6.2168 0.06055-0.19725 0-0.35547 0.16744-0.35547 0.37305v2.5234h-3.7051v-2.5234c0-0.20561-0.15821-0.37305-0.35547-0.37305h-4.416c-0.19725 0-0.35742 0.16744-0.35742 0.37305v9.3535c0 0.20561 0.16001 0.36914 0.35742 0.36914h4.416c0.19726 0 0.35547-0.16353 0.35547-0.36914v-2.5254h3.7051v2.5254c0 0.20561 0.15825 0.36914 0.35547 0.36914h2.2363v11.906c-1.2817 0.50867-2.1856 1.7516-2.1856 3.2188v18.037c0 1.9217 1.5471 3.4688 3.4688 3.4688s3.4688-1.5471 3.4688-3.4688v-18.037c0-1.4665-0.90278-2.7096-2.1836-3.2188v-11.906h2.4199c0.38561-0.3394 0.75677-1.7011 2.8164-2.7422 5.5309-1.9 7.9328 2.808 7.8906 2.1582-0.04505-0.69373-0.35053-5.0458-5.1797-7.5977-2.1039-0.94609-4.5788-1.8754-5.2461-1.9141-0.06886-0.03628-0.57246-0.05374-1.2891-0.06055z" stroke="#000" stroke-width=".82412" style="paint-order:markers fill stroke"/> + <path id="path1230" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m650.43 257.96c-1.8975 0.03152-3.3994 0.81663-4.3105 1.4941-1.2149 0.90323-1.6057 1.4192-3.4434 1.4238-1.8376 0.00378-2.2279-0.51106-3.4473-1.4082-1.2194-0.89718-3.4899-1.9778-6.3379-1.207-2.848 0.77069-4.2647 2.8506-4.8652 4.2402-0.60051 1.3896-0.67842 2.0323-2.2676 2.9551-1.5892 0.92281-2.1868 0.67315-3.6914 0.50586-1.5046-0.16743-4.0146 0.03049-6.0957 2.1211-2.0811 2.0914-2.2685 4.6037-2.0938 6.1074 0.17473 1.5038 0.42851 2.0977-0.48633 3.6914-0.91487 1.5937-1.5548 1.6758-2.9414 2.2832-1.3867 0.60741-3.4622 2.031-4.2188 4.8828-0.75654 2.8518 0.34098 5.1191 1.2441 6.334 0.90319 1.2149 1.4192 1.6038 1.4238 3.4414 0.00454 1.8376-0.51104 2.2279-1.4082 3.4473-0.89718 1.2194-1.9797 3.4918-1.209 6.3398 0.77071 2.848 2.8506 4.2628 4.2402 4.8633 1.3896 0.60049 2.0323 0.67844 2.9551 2.2676 0.92276 1.5892 0.67316 2.1868 0.50586 3.6914-0.16728 1.5046 0.0297 4.0146 2.1211 6.0957 2.0915 2.081 4.6037 2.2627 6.1074 2.0879 1.5037-0.17499 2.0996-0.42073 3.6934 0.49414 1.5937 0.91484 1.6738 1.5528 2.2812 2.9395 0.60742 1.3866 2.031 3.4622 4.8828 4.2187 2.8518 0.75655 6.3494-0.68757 6.334-1.2422-0.01587-0.55461-2.3574 0.39899-4.7051-1.0781-2.3477-1.4772-2.1797-2.3888-2.6973-3.5703-0.51759-1.1816-1.4424-3.4001-4.0254-4.8828-2.5829-1.4827-4.9648-1.1626-6.2461-1.0137-1.2813 0.14891-1.3671 0.40955-2.6894-0.90625-1.3224-1.3158-1.0586-1.3996-0.91602-2.6816 0.14257-1.282 0.44867-3.6628-1.0469-6.2383-1.4956-2.5756-3.7163-3.4922-4.9004-4.0039-1.1841-0.51171-1.3857-0.32643-1.873-2.127-0.4873-1.8008-0.22347-1.7481 0.54102-2.7871 0.76447-1.039 2.2242-2.9456 2.2168-5.9238-0.00718-2.9783-1.4764-4.8828-2.2461-5.918-0.76963-1.0352-1.037-0.97811-0.55859-2.7812 0.47833-1.8031 0.68366-1.6172 1.8652-2.1348 1.1816-0.51757 3.4001-1.4444 4.8828-4.0273 1.4827-2.583 1.1626-4.9628 1.0137-6.2441-0.14883-1.2813-0.4076-1.3671 0.90821-2.6895 1.3158-1.3224 1.3976-1.0644 2.6797-0.92187 1.282 0.14249 3.6647 0.45454 6.2402-1.041 2.5755-1.4955 3.4864-3.7163 3.998-4.9004 0.5117-1.1842 0.33013-1.3877 2.1309-1.875 1.8007-0.48733 1.7481-0.22151 2.7871 0.54297 1.039 0.76449 2.9456 2.2242 5.9238 2.2168 2.9783-0.00756 4.8789-1.4765 5.9141-2.2461 1.0352-0.76967 0.97813-1.0369 2.7812-0.5586 1.8031 0.47834 1.6211 0.68368 2.1387 1.8652 0.51758 1.1816 1.4444 3.4001 4.0273 4.8828s4.9648 1.1626 6.2461 1.0137c1.2813-0.14891 1.3651-0.40955 2.6875 0.90625 1.3224 1.3158 1.0605 1.3996 0.91796 2.6816-0.14252 1.282-0.45062 3.6627 1.0449 6.2383 1.4955 2.5755 3.7162 3.4883 4.9004 4 1.1841 0.51171 1.3877 0.33014 1.875 2.1309 0.4873 1.8007 0.22346 1.7481-0.54102 2.7871-0.76448 1.039-2.2262 2.9456-2.2188 5.9238 0.00756 2.9783 1.4765 4.8769 2.2461 5.9121 0.76965 1.0352 1.0369 0.98006 0.5586 2.7832-0.47834 1.8031-0.68366 1.6211-1.8652 2.1387-1.1816 0.51757-3.4001 1.4444-4.8828 4.0274-1.4827 2.583-1.1606 4.9628-1.0117 6.2441 0.14892 1.2813 0.40761 1.3671-0.9082 2.6894s-1.3996 1.0585-2.6816 0.91602c-1.2821-0.14249-3.6627-0.44865-6.2383 1.0469-2.5756 1.4956-3.4922 3.7163-4.0039 4.9004-0.42099 0.97425-0.43116 1.2881-1.4023 1.6387-0.14024-0.07689-0.29879-0.15062-0.49024-0.22265-1.6607-0.62483-1.8791 0.22103-3.2422 1.2363-1.2238 0.91157-2.0954 1.0256-2.0469 2.2246-0.11719-0.01207-0.22826-0.01416-0.3164-0.00391-0.27829 0.03402-0.38865 0.07948-0.6836-0.08984-0.29495-0.16933-0.30944-0.2883-0.42187-0.54493-0.11241-0.25663-0.3746-0.64125-0.90235-0.78125-0.52779-0.13984-1.1767 0.12767-1.1738 0.23047 0.00294 0.10243 0.43663-0.07442 0.8711 0.19922 0.43447 0.27326 0.40421 0.44147 0.5 0.66016 0.09573 0.21883 0.26613 0.62986 0.74414 0.90429 0.47801 0.2744 0.91911 0.21509 1.1562 0.1875 0.17999-0.02008 0.25507-0.01351 0.37695 0.07813 0.37226 1.1966 1.2449 1.0814 2.752 1.6484 1.6608 0.62483 2.1701 1.3766 3.5332 0.36133 0.99774-0.74318 0.89279-1.2827 0.65234-2.1582 2.2207-0.92783 3.3884-2.6886 3.918-3.9141 0.60051-1.3897 0.67842-2.0323 2.2676-2.9551s2.1868-0.67314 3.6914-0.50586c1.5046 0.16743 4.0146-0.03045 6.0957-2.1211 2.0811-2.0914 2.2685-4.6037 2.0938-6.1074-0.17477-1.5037-0.42853-2.0977 0.48633-3.6914 0.91486-1.5938 1.5548-1.6758 2.9414-2.2832 1.3866-0.60741 3.4622-2.031 4.2188-4.8828 0.75654-2.8518-0.34091-5.1191-1.2441-6.334-0.90322-1.2149-1.4193-1.6038-1.4238-3.4414-0.00453-1.8376 0.51104-2.2279 1.4082-3.4473 0.89716-1.2194 1.9797-3.4919 1.209-6.3398-0.77071-2.848-2.8506-4.2628-4.2402-4.8633-1.3896-0.60053-2.0323-0.68035-2.9551-2.2695-0.92278-1.5891-0.67315-2.1849-0.50586-3.6894 0.16728-1.5046-0.02971-4.0166-2.1211-6.0977-2.0914-2.0811-4.6037-2.2666-6.1074-2.0918-1.5037 0.17499-2.0996 0.42659-3.6934-0.48829-1.5937-0.91487-1.6738-1.5528-2.2812-2.9394-0.60741-1.3867-2.033-3.4622-4.8848-4.2188-0.71295-0.18913-1.389-0.26246-2.0215-0.25195z" style="paint-order:markers fill stroke"/> + <g id="text1242" stroke-width=".22458" aria-label="SETUP"> + <path id="path1372" d="m70.306 150.91q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21054 2.1639 0.21054 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28072-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15207-2.1639-0.15207-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.08773 0.15791-0.12867 0.32167-0.03509 0.16376-0.03509 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61994 0.30412 0.38016 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247t-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1374" d="m74.16 142.58h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1376" d="m85.009 142.58v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1378" d="m85.752 142.58h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67843 0.29242 0.25733 0.70767 0.25733t0.70182-0.25733q0.29243-0.25734 0.38015-0.67843 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52051-1.6376 0.52051-0.95331 0-1.6434-0.52051-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1380" d="m93.607 143.98v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75445 0-0.44449-0.23979-0.75446-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87142 0.52637 0.66673 0.52637 1.6376 0 0.97085-0.52637 1.6434-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1246" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1361" d="m102.96 142.58v1.4036h-1.8715v6.8311h-1.4972v-6.8311h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1363" d="m105.19 145.19q-0.0877 0.47958-0.0877 1.5089t0.0877 1.5089q0.10528 0.56731 0.38601 0.93576 0.28657 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36845 0.39185-0.93576 0.0877-0.48542 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45619 0-0.74276 0.36846-0.28073 0.36261-0.38601 0.92991zm-1.4212 3.55q-0.16376-0.64919-0.16376-2.0411 0-1.392 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64919-0.6141 1.6668-0.6141t1.6668 0.6141q0.64919 0.60824 0.88313 1.5557 0.16375 0.64918 0.16375 2.0411 0 1.3919-0.16375 2.0411-0.23394 0.94746-0.88313 1.5616-0.64918 0.60824-1.6668 0.60824t-1.6668-0.60824q-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1365" d="m111.18 145.19q-0.0877 0.47958-0.0877 1.5089t0.0877 1.5089q0.10527 0.56731 0.386 0.93576 0.28658 0.36261 0.74276 0.36261t0.73691-0.36261q0.28658-0.36845 0.39185-0.93576 0.0877-0.48542 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.5673-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846t-0.74276 0.36846q-0.28073 0.36261-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64919-0.16376-2.0411 0-1.392 0.16376-2.0411 0.23394-0.94746 0.88313-1.5557 0.64918-0.6141 1.6668-0.6141t1.6668 0.6141q0.64919 0.60824 0.88313 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.3919-0.16376 2.0411-0.23394 0.94746-0.88313 1.5616-0.64918 0.60824-1.6668 0.60824t-1.6668-0.60824q-0.64919-0.61409-0.88313-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1367" d="m116.04 150.81v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1369" d="m124.15 150.91q-0.95916 0-2.164-0.18715v-1.427q1.4095 0.21054 2.164 0.21054 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28072-0.41524-0.386-0.16961-0.0643-0.46789-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69013 1.661-0.69013 0.78954 0 2.1639 0.14621v1.4095q-1.4212-0.15207-2.1639-0.15207-0.22225 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.0877 0.15791-0.12867 0.32167-0.0351 0.16376-0.0351 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69013 0.15791 0.54391 0.0819 0.87727 0.25733 0.46788 0.23979 0.77201 0.61994 0.30412 0.38016 0.42109 0.76616t0.11697 0.80124q0 1.1346-0.70182 1.8247t-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <path id="rect1252" d="m45.345 167.28h82.571c0.28796 0 0.51978 0.23182 0.51978 0.51978v22.171c0 0.28796-0.23182 0.51978-0.51978 0.51978h-82.571c-0.28796 0-0.51978-0.23182-0.51978-0.51978v-22.171c0-0.28796 0.23182-0.51978 0.51978-0.51978z" style="paint-order:markers fill stroke"/> + <path id="rect1254" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m645.59 394.06c-2.1498-0.02041-6.2168 0.06055-6.2168 0.06055-0.19725 0-0.35547 0.16744-0.35547 0.37304v2.5234h-3.7051v-2.5234c0-0.2056-0.15821-0.37304-0.35547-0.37304h-4.416c-0.19725 0-0.35742 0.16744-0.35742 0.37304v9.3535c0 0.20561 0.16001 0.37109 0.35742 0.37109h4.416c0.19726 0 0.35547-0.16548 0.35547-0.37109v-2.5234h3.7051v2.5234c0 0.20561 0.15825 0.37109 0.35547 0.37109h2.2363v11.904c-1.2817 0.50867-2.1856 1.7516-2.1856 3.2188v18.037c0 1.9216 1.5471 3.4688 3.4688 3.4688s3.4688-1.5471 3.4688-3.4688v-18.037c0-1.4665-0.90278-2.7096-2.1836-3.2188v-11.904h2.4199c0.38561-0.3394 0.75677-1.7031 2.8164-2.7441 5.5309-1.9 7.9328 2.808 7.8906 2.1582-0.04505-0.69374-0.35053-5.0458-5.1797-7.5977-2.1039-0.94609-4.5788-1.8754-5.2461-1.9141-0.06886-0.03629-0.57246-0.05375-1.2891-0.06055z" fill="#fff" stroke="#fff" stroke-width=".82412" style="paint-order:markers fill stroke"/> + <path id="path1262" transform="matrix(.26458 0 0 .26458 -113.76 68.446)" d="m650.43 379.6c-1.8975 0.03152-3.3994 0.81663-4.3105 1.4941-1.2149 0.90323-1.6057 1.4212-3.4434 1.4258-1.8376 0.00378-2.2279-0.51301-3.4473-1.4102-1.2194-0.89718-3.4899-1.9778-6.3379-1.207-2.848 0.77068-4.2647 2.8506-4.8652 4.2402-0.60051 1.3896-0.67842 2.0323-2.2676 2.9551-1.5892 0.92281-2.1868 0.67314-3.6914 0.50586-1.5046-0.16743-4.0146 0.03049-6.0957 2.1211-2.0811 2.0914-2.2685 4.6037-2.0938 6.1074 0.17473 1.5038 0.42851 2.0996-0.48633 3.6934-0.91487 1.5937-1.5548 1.6738-2.9414 2.2812-1.3867 0.60741-3.4622 2.031-4.2188 4.8828-0.75654 2.8518 0.34098 5.1191 1.2441 6.334 0.90319 1.2149 1.4192 1.6038 1.4238 3.4414 0.00454 1.8376-0.51104 2.2279-1.4082 3.4473-0.89718 1.2194-1.9797 3.4918-1.209 6.3398 0.77071 2.848 2.8506 4.2628 4.2402 4.8633 1.3896 0.60049 2.0323 0.68039 2.9551 2.2695 0.92276 1.5892 0.67316 2.1849 0.50586 3.6895-0.16728 1.5046 0.0297 4.0166 2.1211 6.0976 2.0915 2.081 4.6037 2.2627 6.1074 2.0879 1.5037-0.17461 2.0996-0.42268 3.6934 0.49219 1.5937 0.91483 1.6738 1.5528 2.2812 2.9394 0.60742 1.3866 2.031 3.4622 4.8828 4.2188 2.8518 0.75655 6.3494-0.68758 6.334-1.2422-0.01587-0.55461-2.3574 0.39899-4.7051-1.0781-2.3477-1.4772-2.1797-2.3888-2.6973-3.5703-0.51759-1.1816-1.4424-3.4001-4.0254-4.8828-2.5829-1.4827-4.9648-1.1626-6.2461-1.0137-1.2813 0.14892-1.3671 0.40956-2.6894-0.90625-1.3224-1.3158-1.0586-1.3996-0.91602-2.6816 0.14257-1.282 0.44867-3.6628-1.0469-6.2383-1.4956-2.5756-3.7163-3.4922-4.9004-4.0039-1.1841-0.51171-1.3857-0.32643-1.873-2.127-0.4873-1.8008-0.22347-1.7481 0.54102-2.7871 0.76447-1.039 2.2242-2.9456 2.2168-5.9238-0.00718-2.9783-1.4764-4.8828-2.2461-5.918-0.76963-1.0352-1.037-0.97812-0.55859-2.7812 0.47833-1.8031 0.68366-1.6172 1.8652-2.1348 1.1816-0.51757 3.4001-1.4444 4.8828-4.0273 1.4827-2.583 1.1626-4.9628 1.0137-6.2441-0.14883-1.2813-0.4076-1.3671 0.90821-2.6895s1.3976-1.0644 2.6797-0.92187c1.282 0.14249 3.6647 0.45454 6.2402-1.041 2.5755-1.4955 3.4864-3.7163 3.998-4.9004 0.5117-1.1842 0.33013-1.3877 2.1309-1.875 1.8007-0.48733 1.7481-0.22151 2.7871 0.54297 1.039 0.76449 2.9456 2.2242 5.9238 2.2168 2.9783-0.00756 4.8789-1.4765 5.9141-2.2461 1.0352-0.76966 0.97813-1.0369 2.7812-0.55859 1.8031 0.47834 1.6211 0.68368 2.1387 1.8652 0.51758 1.1816 1.4444 3.4001 4.0273 4.8828s4.9648 1.1626 6.2461 1.0137c1.2813-0.14891 1.3651-0.40956 2.6875 0.90625 1.3224 1.3158 1.0605 1.3996 0.91796 2.6816-0.14252 1.282-0.45062 3.6627 1.0449 6.2383 1.4955 2.5755 3.7162 3.4883 4.9004 4 1.1841 0.51171 1.3877 0.33014 1.875 2.1309 0.4873 1.8007 0.22346 1.7481-0.54102 2.7871-0.76448 1.039-2.2262 2.9456-2.2188 5.9238 0.00756 2.9783 1.4765 4.8769 2.2461 5.9121 0.76965 1.0352 1.0369 0.98006 0.5586 2.7832-0.47834 1.8031-0.68366 1.6211-1.8652 2.1387-1.1816 0.51757-3.4001 1.4444-4.8828 4.0274-1.4827 2.583-1.1606 4.9628-1.0117 6.2441 0.14892 1.2813 0.40761 1.3671-0.9082 2.6894s-1.3996 1.0605-2.6816 0.91797c-1.2821-0.14249-3.6627-0.4506-6.2383 1.0449-2.5756 1.4956-3.4922 3.7163-4.0039 4.9004-0.42128 0.97492-0.43101 1.2897-1.4043 1.6406-0.13992-0.07663-0.29747-0.15087-0.48828-0.22266-1.6607-0.62483-1.8791 0.21908-3.2422 1.2344-1.2233 0.91121-2.0946 1.027-2.0469 2.2246-0.11719-0.01206-0.22826-0.01415-0.3164-0.0039-0.27829 0.03401-0.38865 0.07948-0.6836-0.08985-0.29495-0.16932-0.30944-0.28829-0.42187-0.54492-0.11241-0.25663-0.3746-0.64125-0.90235-0.78125-0.52779-0.13984-1.1767 0.12767-1.1738 0.23047 0.00294 0.10243 0.43663-0.07442 0.8711 0.19922 0.43447 0.27326 0.40421 0.44343 0.5 0.66211 0.09573 0.21883 0.26613 0.62791 0.74414 0.90234 0.47801 0.2744 0.91911 0.21509 1.1562 0.1875 0.17999-0.02008 0.25507-0.01352 0.37695 0.07813 0.37226 1.1966 1.2449 1.0814 2.752 1.6484 1.6608 0.62483 2.1701 1.3766 3.5332 0.36133 0.99774-0.74318 0.89279-1.2827 0.65234-2.1582 2.2207-0.92783 3.3884-2.6886 3.918-3.9141 0.60051-1.3897 0.67842-2.0323 2.2676-2.9551s2.1868-0.67314 3.6914-0.50586c1.5046 0.16743 4.0146-0.03045 6.0957-2.1211 2.0811-2.0914 2.2685-4.6037 2.0938-6.1074-0.17477-1.5037-0.42853-2.0977 0.48633-3.6914 0.91486-1.5938 1.5548-1.6758 2.9414-2.2832 1.3866-0.6074 3.4622-2.031 4.2188-4.8828 0.75654-2.8518-0.34091-5.1191-1.2441-6.334-0.90322-1.2149-1.4193-1.6038-1.4238-3.4414-0.00453-1.8376 0.51104-2.2279 1.4082-3.4473 0.89716-1.2194 1.9797-3.4919 1.209-6.3398-0.77071-2.848-2.8506-4.2628-4.2402-4.8633-1.3896-0.60053-2.0323-0.6784-2.9551-2.2676-0.92278-1.5891-0.67315-2.1868-0.50586-3.6914 0.16728-1.5046-0.02971-4.0147-2.1211-6.0957-2.0914-2.0811-4.6037-2.2685-6.1074-2.0938-1.5037 0.17462-2.0996 0.42659-3.6934-0.48828-1.5937-0.91487-1.6738-1.5528-2.2812-2.9394-0.60741-1.3867-2.033-3.4622-4.8848-4.2188-0.71295-0.18913-1.389-0.26246-2.0215-0.25195z" fill="#fff" style="paint-order:markers fill stroke"/> + <g id="text1274" fill="#fff" stroke-width=".22458" aria-label="SETUP"> + <path id="path1333" d="m70.306 183.09q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.08773 0.15791-0.12867 0.32167-0.03509 0.16376-0.03509 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25733 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1335" d="m74.16 174.76h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1337" d="m85.009 174.76v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1339" d="m85.752 174.76h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29243-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82464-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052-0.95331 0-1.6434-0.52052-0.68428-0.52051-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1341" d="m93.607 176.17v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446 0-0.44448-0.23979-0.75445-0.23394-0.30998-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52637 0.66673 0.52637 1.6376 0 0.97086-0.52637 1.6434-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1278" fill="#fff" stroke-width=".22458" aria-label="TOOLS"> + <path id="path1344" d="m102.96 174.76v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1346" d="m105.19 177.37q-0.0877 0.47958-0.0877 1.5089 0 1.0293 0.0877 1.5089 0.10528 0.56731 0.38601 0.93576 0.28657 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36845 0.39185-0.93576 0.0877-0.48543 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45619 0-0.74276 0.36846-0.28073 0.3626-0.38601 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88312-1.5557 0.64919-0.61409 1.6668-0.61409t1.6668 0.61409q0.64919 0.60825 0.88313 1.5557 0.16375 0.64918 0.16375 2.0411 0 1.392-0.16375 2.0411-0.23394 0.94746-0.88313 1.5616-0.64918 0.60824-1.6668 0.60824t-1.6668-0.60824q-0.64918-0.6141-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1348" d="m111.18 177.37q-0.0877 0.47958-0.0877 1.5089 0 1.0293 0.0877 1.5089 0.10527 0.56731 0.386 0.93576 0.28658 0.36261 0.74276 0.36261t0.73691-0.36261q0.28658-0.36845 0.39185-0.93576 0.0877-0.48543 0.0877-1.5089 0-1.0293-0.0877-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846t-0.74276 0.36846q-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94746 0.88313-1.5557 0.64918-0.61409 1.6668-0.61409t1.6668 0.61409q0.64919 0.60825 0.88313 1.5557 0.16376 0.64918 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88313 1.5616-0.64918 0.60824-1.6668 0.60824t-1.6668-0.60824q-0.64919-0.6141-0.88313-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1350" d="m116.04 183v-8.2347h1.4972v6.831h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1352" d="m124.15 183.09q-0.95916 0-2.164-0.18715v-1.427q1.4095 0.21055 2.164 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46789-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78954 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22225 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25733-0.0877 0.15791-0.12867 0.32167-0.0351 0.16376-0.0351 0.32167 0 0.69012 0.46788 0.90067 0.15206 0.0702 0.69013 0.15791 0.54391 0.0819 0.87727 0.25733 0.46788 0.23979 0.77201 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> +</svg> diff --git a/docs/images/logo-editable-inkscape.svg b/docs/images/logo-editable-inkscape.svg new file mode 100644 index 00000000..1b323a5d --- /dev/null +++ b/docs/images/logo-editable-inkscape.svg @@ -0,0 +1,150 @@ +<?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:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="60.536667mm" + height="56.932983mm" + viewBox="0 0 60.536667 56.932983" + version="1.1" + id="svg1021" + inkscape:version="0.92.4 (5da689c313, 2019-01-14)" + sodipodi:docname="editable-inkscape.svg"> + <defs + id="defs1015" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.979899" + inkscape:cx="45.267489" + inkscape:cy="111.94099" + inkscape:document-units="mm" + 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="1080" + inkscape:window-height="1867" + inkscape:window-x="-8" + inkscape:window-y="-8" + inkscape:window-maximized="1" /> + <metadata + id="metadata1018"> + <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 /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-24.953698,-78.736052)"> + <g + id="g982"> + <g + id="g960"> + <g + id="g945"> + <rect + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.47744644;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect934" + width="4.0191145" + height="14.468813" + x="53.291348" + y="100.62229" + ry="2.0095572" /> + <rect + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.66292131;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="rect936" + width="1.4879318" + height="10.046045" + x="54.55695" + y="93.042908" + ry="0.41858676" /> + <path + style="fill:#e5b62f;fill-opacity:1;fill-rule:nonzero;stroke:#e5b62f;stroke-width:0.25023597;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + d="m 48.144574,88.021103 c -0.114286,0 -0.20651,0.09612 -0.20651,0.215203 v 5.418959 c 0,0.119095 0.09215,0.214869 0.20651,0.214869 h 2.558873 c 0.114286,0 0.206196,-0.09576 0.206196,-0.214869 v -1.46217 h 2.146166 v 1.46217 c 0,0.119095 0.09191,0.214869 0.206185,0.214869 h 4.185409 c 0.2234,-0.196683 0.438739,-0.985748 1.631974,-1.588904 3.20429,-1.100736 4.595709,1.626427 4.571299,1.249968 -0.0261,-0.401914 -0.203838,-2.922739 -3.00157,-4.401161 -1.218894,-0.548102 -2.652009,-1.086539 -3.038574,-1.108934 -0.15958,-0.08409 -4.348538,0 -4.348538,0 -0.114286,0 -0.206185,0.09612 -0.206185,0.215203 v 1.462181 h -2.146166 v -1.462181 c 0,-0.119095 -0.09191,-0.215203 -0.206196,-0.215203 z" + id="path938" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ssssssccsscccccssccsss" /> + </g> + <g + id="g950"> + <path + sodipodi:type="star" + style="fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.69700003;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke" + id="path944" + sodipodi:sides="3" + sodipodi:cx="64.20871" + sodipodi:cy="71.820686" + sodipodi:r1="7.6796398" + sodipodi:r2="5.736691" + sodipodi:arg1="1.2451547" + sodipodi:arg2="2.2923522" + inkscape:flatsided="false" + inkscape:rounded="0.5" + inkscape:randomized="0" + d="m 66.665555,79.096728 c -3.276257,1.106269 -3.650052,-0.684868 -6.246237,-2.969055 -2.596186,-2.284188 -4.420339,-2.42686 -3.740268,-5.817317 0.680072,-3.390456 2.418139,-2.818604 5.694396,-3.924873 3.276257,-1.106268 4.311892,-2.614696 6.908078,-0.330508 2.596185,2.284187 1.231913,3.503471 0.551841,6.893928 -0.680071,3.390456 0.108448,5.041556 -3.16781,6.147825 z" + inkscape:transform-center-x="-0.011614295" + inkscape:transform-center-y="0.11269997" + transform="matrix(-0.04632163,0.27242436,-0.29307005,-0.05212312,83.678657,107.67792)" /> + <path + sodipodi:nodetypes="ccssszzsccc" + inkscape:connector-curvature="0" + id="path946" + d="m 57.854781,121.68027 c -0.224242,-0.22312 -0.493595,-0.2426 -0.654821,-0.22386 -0.161227,0.0187 -0.225057,0.0453 -0.395933,-0.0528 -0.170875,-0.0981 -0.179541,-0.16664 -0.244666,-0.31532 -0.06513,-0.14866 -0.217817,-0.37118 -0.52357,-0.45229 -0.305773,-0.0811 -0.6807,0.0738 -0.679032,0.13328 0.0017,0.0594 0.252729,-0.0429 0.504435,0.11553 0.251708,0.15838 0.233668,0.25615 0.28916,0.38283 0.05547,0.1267 0.154811,0.36455 0.431741,0.52352 0.276935,0.15897 0.532206,0.12454 0.669588,0.10856 0.137383,-0.016 0.14656,-0.0438 0.288337,0.0973" + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.44643572;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /> + <path + style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#336790;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:2.41228795;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:markers fill stroke;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + d="m 60.940298,122.04817 c 1.649958,-0.44651 2.47031,-1.65141 2.818208,-2.45649 0.347899,-0.80508 0.393415,-1.17719 1.31408,-1.71179 0.920667,-0.53461 1.266547,-0.39025 2.138212,-0.29333 0.871666,0.0969 2.326155,-0.017 3.531808,-1.22871 1.205653,-1.21166 1.313866,-2.66723 1.212614,-3.5384 -0.101258,-0.87117 -0.247684,-1.21597 0.282334,-2.13929 0.530018,-0.92331 0.900404,-0.97013 1.703746,-1.32204 0.803343,-0.3519 2.005659,-1.17695 2.443952,-2.82911 0.438293,-1.65216 -0.19692,-2.96527 -0.72019,-3.6691 -0.523273,-0.70383 -0.82256,-0.9295 -0.825208,-1.99413 -0.0026,-1.064618 0.296407,-1.290647 0.816172,-1.997071 0.519766,-0.706424 1.146255,-2.022589 0.699748,-3.672551 -0.446507,-1.649957 -1.65141,-2.470309 -2.456492,-2.818207 -0.805083,-0.347898 -1.177187,-0.393415 -1.711792,-1.314079 -0.534603,-0.920664 -0.390244,-1.266546 -0.293327,-2.138211 0.09692,-0.871669 -0.01704,-2.326158 -1.228708,-3.531807 -1.211665,-1.205655 -2.667225,-1.31387 -3.538398,-1.212617 -0.871171,0.101258 -1.215974,0.247683 -2.139288,-0.282335 -0.923315,-0.530018 -0.97014,-0.900403 -1.32204,-1.703747 -0.3519,-0.803343 -1.176952,-2.005655 -2.829111,-2.443952 -1.652159,-0.438291 -2.965275,0.19692 -3.669107,0.720192 -0.703831,0.523271 -0.929503,0.822562 -1.994125,0.825206 -1.06462,0.0027 -1.290651,-0.296403 -1.997073,-0.81617 -0.706422,-0.519766 -2.022584,-1.146253 -3.672549,-0.699747 -1.649965,0.446506 -2.470309,1.651408 -2.818207,2.456494 -0.347897,0.80508 -0.393415,1.177185 -1.314081,1.711788 -0.920667,0.534604 -1.266544,0.390243 -2.138219,0.293329 -0.871661,-0.09692 -2.326146,0.01704 -3.531796,1.228706 -1.205665,1.211665 -1.313865,2.667229 -1.212622,3.538399 0.101228,0.871175 0.247679,1.215976 -0.282328,2.139291 -0.530022,0.923314 -0.900407,0.970137 -1.703752,1.322035 -0.803345,0.351903 -2.005655,1.176954 -2.443951,2.829115 -0.438297,1.65216 0.196949,2.965272 0.720196,3.669104 0.523262,0.703833 0.822555,0.929502 0.825202,1.994125 0.0026,1.06463 -0.296408,1.29065 -0.816166,1.99707 -0.519773,0.70643 -1.146256,2.02259 -0.699751,3.67256 0.446504,1.64995 1.651404,2.4703 2.456496,2.8182 0.805077,0.3479 1.177181,0.39342 1.711791,1.31408 0.534596,0.92067 0.390243,1.26655 0.29332,2.13822 -0.09692,0.87166 0.01697,2.32615 1.22871,3.5318 1.211667,1.20565 2.667117,1.31092 3.538291,1.20967 0.871174,-0.10126 1.216081,-0.24474 2.139395,0.28528 0.923314,0.53002 0.970135,0.9004 1.322038,1.70375 0.351903,0.80334 1.176962,2.00565 2.829116,2.44395 1.652154,0.43829 3.678064,-0.39888 3.669103,-0.72019 -0.0091,-0.32131 -1.36561,0.23146 -2.725712,-0.62431 -1.360103,-0.85577 -1.262592,-1.38409 -1.562452,-2.06862 -0.299861,-0.68454 -0.836482,-1.96979 -2.332901,-2.82878 -1.496403,-0.859 -2.875745,-0.67295 -3.618077,-0.58667 -0.742333,0.0863 -0.791919,0.23659 -1.55802,-0.52571 -0.7661,-0.76231 -0.613628,-0.81078 -0.531048,-1.55353 0.0826,-0.74276 0.260494,-2.12226 -0.605939,-3.61438 -0.866433,-1.49212 -2.153156,-2.02313 -2.839171,-2.31957 -0.686016,-0.29645 -0.803414,-0.18822 -1.08573,-1.23144 -0.282314,-1.04324 -0.128956,-1.01302 0.313953,-1.61498 0.442894,-0.60195 1.288828,-1.70645 1.28453,-3.43187 -0.0042,-1.725436 -0.85569,-2.82894 -1.301572,-3.428677 -0.445882,-0.599742 -0.600745,-0.566939 -0.323613,-1.611558 0.277117,-1.044618 0.396544,-0.936667 1.081078,-1.236522 0.684535,-0.299855 1.969781,-0.83648 2.828786,-2.332894 0.858989,-1.496414 0.672935,-2.875755 0.586655,-3.618089 -0.08623,-0.742334 -0.23659,-0.791909 0.525716,-1.558015 0.762305,-0.766106 0.81067,-0.616579 1.553425,-0.533996 0.74274,0.08258 2.122366,0.263444 3.614487,-0.602989 1.492121,-0.866428 2.020167,-2.153042 2.316617,-2.83906 0.296451,-0.686017 0.19116,-0.803526 1.234391,-1.08584 1.043233,-0.282319 1.013019,-0.128943 1.614974,0.313945 0.601955,0.442893 1.706455,1.288834 3.431877,1.284539 1.725431,-0.0043 2.825988,-0.855575 3.425728,-1.301457 0.599739,-0.445887 0.566934,-0.600752 1.611554,-0.323626 1.044619,0.27712 0.939616,0.396436 1.239472,1.080969 0.299856,0.684534 0.836481,1.969783 2.332894,2.828782 1.496412,0.858999 2.875756,0.672943 3.618087,0.586662 0.742332,-0.08628 0.79191,-0.236587 1.558016,0.525718 0.766106,0.762305 0.613632,0.810778 0.531049,1.553532 -0.08258,0.742747 -0.260498,2.122255 0.605934,3.614374 0.866431,1.492119 2.153047,2.02018 2.839064,2.316621 0.686018,0.296452 0.803526,0.191168 1.085841,1.234394 0.282315,1.043226 0.128942,1.01302 -0.313948,1.614971 -0.442896,0.601946 -1.288832,1.706446 -1.284541,3.431876 0.0043,1.72543 0.855578,2.82599 1.301461,3.42573 0.445885,0.59974 0.600748,0.56693 0.323626,1.61155 -0.277122,1.04463 -0.396439,0.93962 -1.080972,1.23948 -0.684535,0.29985 -1.969784,0.83648 -2.828783,2.33289 -0.858997,1.49641 -0.672941,2.87575 -0.586662,3.61809 0.08628,0.74233 0.236591,0.79191 -0.525715,1.55801 -0.762305,0.76611 -0.810779,0.61364 -1.55353,0.53105 -0.742752,-0.0826 -2.122255,-0.26049 -3.614376,0.60593 -1.49212,0.86644 -2.023126,2.15316 -2.319573,2.83918 -0.296448,0.68602 -0.188214,0.80342 -1.231443,1.08573" + id="path942" + inkscape:connector-curvature="0" + sodipodi:nodetypes="csscscssscsscsscccssscscssscccccscccsccsccssszzsccscscsccscsccscssscccssscscscsccccsccscscc" /> + </g> + </g> + <g + id="g966"> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#336790;fill-opacity:1;stroke:none;stroke-width:0.22458273" + x="24.929686" + y="134.70683" + id="text1023"><tspan + sodipodi:role="line" + id="tspan1021" + x="24.929686" + y="134.70683" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#336790;fill-opacity:1;stroke-width:0.22458273">SETUP</tspan></text> + <text + id="text1661" + y="134.70683" + x="54.844803" + style="font-style:normal;font-weight:normal;font-size:8.98330784px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#e5b62f;fill-opacity:1;stroke:none;stroke-width:0.22458273" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.98330784px;font-family:Monoid;-inkscape-font-specification:'Monoid Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#e5b62f;fill-opacity:1;stroke-width:0.22458273" + y="134.70683" + x="54.844803" + id="tspan1659" + sodipodi:role="line">TOOLS</tspan></text> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo-inline-negative.svg b/docs/images/logo-inline-negative.svg new file mode 100644 index 00000000..4bf63cfe --- /dev/null +++ b/docs/images/logo-inline-negative.svg @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="83.811mm" height="23.41mm" version="1.1" viewBox="0 0 83.811 23.41" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <rect id="rect830" x=".1" y=".1" width="83.611" height="23.21" ry=".51978" fill="#336790" style="paint-order:markers fill stroke"/> + <g id="layer1" transform="translate(-2.6008 -95.497)"> + <g id="g1751" transform="matrix(.4567 0 0 .4567 -11.042 60.847)"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#fff" style="paint-order:markers fill stroke"/> + </g> + <g id="g1747" transform="translate(0 -23.387)" stroke-width=".22458"> + <g id="text1023" fill="#fff" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo-inline.svg b/docs/images/logo-inline.svg new file mode 100644 index 00000000..6e45103d --- /dev/null +++ b/docs/images/logo-inline.svg @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="80.121mm" height="20mm" version="1.1" viewBox="0 0 80.121 20" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <g id="layer1" transform="translate(-4.4456 -97.203)"> + <g id="g1751" transform="matrix(.4567 0 0 .4567 -11.042 60.847)"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#336790" style="paint-order:markers fill stroke"/> + </g> + <g id="g1747" transform="translate(0 -23.387)" stroke-width=".22458"> + <g id="text1023" fill="#336790" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo-negative.svg b/docs/images/logo-negative.svg new file mode 100644 index 00000000..d2142045 --- /dev/null +++ b/docs/images/logo-negative.svg @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="64.584mm" height="60.752mm" version="1.1" viewBox="0 0 64.584 60.752" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <rect id="rect830" x=".1" y=".1" width="64.384" height="60.552" ry="1.5737" fill="#336790" style="paint-order:markers fill stroke"/> + <g id="layer1" transform="translate(-22.93 -76.827)"> + <g id="g1769"> + <g id="g1751"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#fff" style="paint-order:markers fill stroke"/> + </g> + <g id="g1747" stroke-width=".22458"> + <g id="text1023" fill="#fff" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo-over-white.svg b/docs/images/logo-over-white.svg new file mode 100644 index 00000000..1ed01380 --- /dev/null +++ b/docs/images/logo-over-white.svg @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="64.584mm" height="60.752mm" version="1.1" viewBox="0 0 64.584 60.752" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <rect id="rect1616" x=".1" y=".1" width="64.384" height="60.552" ry="1.5737" fill="#fff" style="paint-order:markers fill stroke"/> + <g id="layer1" transform="translate(-22.93 -76.827)"> + <g id="g1769"> + <g id="g1751"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#336790" style="paint-order:markers fill stroke"/> + </g> + <g id="g1747" stroke-width=".22458"> + <g id="text1023" fill="#336790" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo-symbol-only.svg b/docs/images/logo-symbol-only.svg new file mode 100644 index 00000000..2bbf2d58 --- /dev/null +++ b/docs/images/logo-symbol-only.svg @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="192" height="192" version="1.1" viewBox="0 0 50.8 50.8" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <g id="layer1" transform="matrix(1.1479 0 0 1.1479 -37.991 -97.66)"> + <g id="g1769"> + <g id="g1751" transform="translate(.00014743 5.7013)"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#336790" style="paint-order:markers fill stroke"/> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo-text-only.svg b/docs/images/logo-text-only.svg new file mode 100644 index 00000000..2e92580d --- /dev/null +++ b/docs/images/logo-text-only.svg @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="59.49mm" height="9.2219mm" version="1.1" viewBox="0 0 59.49 9.2219" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <g id="layer1" transform="translate(-25.477 -102.59)"> + <g id="g1747" transform="translate(0 -23.387)" stroke-width=".22458"> + <g id="text1023" fill="#336790" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> +</svg> diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 00000000..7c793a08 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg id="svg1021" width="60.537mm" height="56.933mm" version="1.1" viewBox="0 0 60.537 56.933" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <metadata id="metadata1018"> + <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/> + </cc:Work> + </rdf:RDF> + </metadata> + <g id="layer1" transform="translate(-24.954 -78.736)"> + <g id="g1769"> + <g id="g1751"> + <path id="rect934" d="m56.864 87.986c-1.2455-0.01183-3.6018 0.03564-3.6018 0.03564-0.11429 0-0.20619 0.09589-0.20619 0.21498v1.4624h-2.1461v-1.4624c0-0.1191-0.0919-0.21498-0.20619-0.21498h-2.559c-0.11429 0-0.2067 0.09589-0.2067 0.21498v5.4188c0 0.1191 0.09235 0.21498 0.2067 0.21498h2.559c0.11429 0 0.20619-0.09587 0.20619-0.21498v-1.4619h2.1461v1.4619c0 0.1191 0.09191 0.21498 0.20619 0.21498h1.295v6.8952c-0.74253 0.29471-1.2656 1.0166-1.2656 1.8666v10.45c0 1.1133 0.89588 2.0092 2.0092 2.0092 1.1133 0 2.0097-0.89589 2.0097-2.0092v-10.45c0-0.84994-0.52302-1.5718-1.2656-1.8666v-6.8952h1.4025c0.2234-0.19668 0.4387-0.98538 1.6319-1.5885 3.2043-1.1007 4.5957 1.626 4.5713 1.2495-0.02611-0.40191-0.20364-2.9223-3.0014-4.4008-1.2189-0.54811-2.652-1.0866-3.0386-1.109-0.03989-0.02102-0.33157-0.03172-0.74672-0.03564z" fill="#e5b62f" stroke="#e5b62f" stroke-width=".47745" style="paint-order:markers fill stroke"/> + <path id="path944" d="m59.665 79.605c-1.0993 0.01828-1.9696 0.47364-2.4975 0.8661-0.70383 0.52328-0.92957 0.82263-1.9942 0.82528-1.0646 0.0027-1.2909-0.2962-1.9973-0.81597-0.70642-0.51977-2.0227-1.1467-3.6726-0.70022-1.65 0.44651-2.47 1.6516-2.8179 2.4567-0.3479 0.80508-0.39346 1.1774-1.3141 1.712-0.92067 0.53461-1.2667 0.38993-2.1384 0.29301-0.87166-0.09692-2.3259 0.0172-3.5316 1.2289-1.2057 1.2117-1.3141 2.6671-1.2128 3.5383 0.10123 0.87118 0.24785 1.2161-0.28215 2.1394-0.53002 0.92331-0.90043 0.96999-1.7038 1.3219s-2.006 1.1771-2.4443 2.8293c-0.4383 1.6522 0.19712 2.9652 0.72037 3.669 0.52326 0.70383 0.82262 0.92957 0.82527 1.9942 0.0026 1.0646-0.29621 1.2904-0.81597 1.9968-0.51977 0.70643-1.1462 2.0227-0.6997 3.6726s1.6511 2.4705 2.4562 2.8184c0.80508 0.3479 1.1774 0.39347 1.712 1.3141 0.5346 0.92066 0.38993 1.2662 0.29301 2.1378-0.09692 0.87166 0.01712 2.3264 1.2289 3.5321 1.2117 1.2056 2.6671 1.311 3.5383 1.2098 0.87117-0.10126 1.2161-0.24477 2.1394 0.28525 0.92331 0.53002 0.96998 0.90043 1.3219 1.7038 0.3519 0.80334 1.1771 2.0055 2.8293 2.4438 1.6522 0.43829 3.678-0.39906 3.669-0.72037-0.0091-0.3213-1.3658 0.23152-2.7259-0.62425s-1.2623-1.3841-1.5622-2.0686c-0.29986-0.68453-0.83626-1.9698-2.3327-2.8288-1.4964-0.859-2.8761-0.67281-3.6184-0.58653-0.74233 0.0863-0.79194 0.23675-1.558-0.52555-0.7661-0.76231-0.6133-0.81116-0.53072-1.5539 0.08259-0.74275 0.26027-2.1221-0.60616-3.6142-0.86643-1.4921-2.1531-2.0228-2.8391-2.3192s-0.80341-0.18822-1.0857-1.2314-0.12923-1.0134 0.31368-1.6154c0.44289-0.60195 1.289-1.7064 1.2847-3.4318-0.0042-1.7254-0.85585-2.829-1.3017-3.4287-0.44588-0.59974-0.60063-0.56665-0.32349-1.6113 0.27712-1.0446 0.39654-0.93676 1.0811-1.2366 0.68454-0.29985 1.9698-0.83626 2.8288-2.3327 0.85899-1.4964 0.67281-2.8761 0.58653-3.6184-0.08624-0.74233-0.23624-0.79194 0.52606-1.558 0.76231-0.76611 0.81064-0.6164 1.5534-0.53382 0.74274 0.08258 2.1221 0.26337 3.6142-0.60306 1.4921-0.86643 2.0202-2.1531 2.3167-2.8391 0.29645-0.68602 0.19132-0.80341 1.2345-1.0857 1.0432-0.28231 1.0129-0.12921 1.6149 0.31368 0.60196 0.44289 1.7064 1.289 3.4318 1.2847 1.7254-0.0043 2.8259-0.85533 3.4256-1.3012 0.59974-0.44589 0.56717-0.60113 1.6118-0.32401 1.0446 0.27712 0.93934 0.39654 1.2392 1.0811 0.29986 0.68453 0.83678 1.9698 2.3332 2.8288 1.4964 0.859 2.8755 0.67332 3.6179 0.58704 0.74233-0.08628 0.79194-0.23676 1.558 0.52555 0.76611 0.7623 0.61382 0.81064 0.53124 1.5534-0.08258 0.74275-0.26078 2.1221 0.60565 3.6142 0.86643 1.4921 2.1531 2.0202 2.8391 2.3167 0.68602 0.29645 0.80392 0.19132 1.0862 1.2346 0.28231 1.0432 0.1287 1.0129-0.31419 1.6149-0.4429 0.60195-1.289 1.7064-1.2847 3.4318 0.0043 1.7254 0.85584 2.8259 1.3017 3.4256 0.44588 0.59974 0.60062 0.56717 0.3235 1.6118-0.27712 1.0446-0.39654 0.93986-1.0811 1.2397-0.68454 0.29985-1.9698 0.83626-2.8288 2.3327-0.859 1.4964-0.6728 2.8755-0.58653 3.6179 0.08628 0.74233 0.23676 0.79194-0.52555 1.558-0.76231 0.76611-0.81116 0.61382-1.5539 0.53124-0.74275-0.0826-2.1221-0.26027-3.6143 0.60616-1.4921 0.86644-2.0233 2.1531-2.3198 2.8391-0.24633 0.57005-0.22224 0.74776-0.80254 0.95343-0.08286-0.046-0.17925-0.0898-0.29352-0.1328-0.96214-0.36199-1.0882 0.12751-1.8779 0.71571-0.71013 0.52895-1.2184 0.5911-1.1886 1.2888-0.06706-7e-3 -0.13033-8e-3 -0.18087-2e-3 -0.16123 0.0187-0.22496 0.0454-0.39584-0.0527-0.17088-0.0981-0.1793-0.16656-0.24443-0.31522-0.06513-0.14868-0.21773-0.37158-0.52348-0.45269-0.30577-0.0811-0.6807 0.0739-0.67903 0.13332 0.0016 0.0594 0.25266-0.0426 0.50436 0.11576 0.25171 0.15837 0.23338 0.25624 0.28887 0.38292 0.05548 0.1267 0.15508 0.36451 0.43202 0.52349 0.27693 0.15896 0.53183 0.12449 0.66921 0.10851 0.1049-0.0122 0.13623-0.0302 0.20774 0.0243 0.21075 0.72266 0.72116 0.6429 1.6056 0.97565 0.96214 0.36199 1.2562 0.7975 2.0459 0.20929 0.57854-0.43092 0.52042-0.74207 0.38086-1.25 1.2857-0.53767 1.9604-1.5578 2.267-2.2676 0.3479-0.80508 0.39347-1.1769 1.3141-1.7115 0.92066-0.5346 1.2662-0.39043 2.1379-0.29351 0.87166 0.0969 2.3264-0.0167 3.5321-1.2284s1.3136-2.6676 1.2123-3.5388c-0.10126-0.87117-0.24735-1.2156 0.28267-2.1389 0.53002-0.92331 0.90043-0.9705 1.7038-1.3224 0.80334-0.35189 2.0055-1.1766 2.4438-2.8288 0.43829-1.6522-0.1971-2.9652-0.72037-3.669-0.52328-0.70383-0.82211-0.92957-0.82476-1.9942-0.0026-1.0646 0.2962-1.2909 0.81597-1.9973 0.51977-0.70642 1.1462-2.0227 0.6997-3.6726-0.4465-1.65-1.6516-2.47-2.4567-2.8179-0.80508-0.3479-1.1769-0.39346-1.7115-1.3141-0.5346-0.92066-0.39044-1.2667-0.29352-2.1384 0.09692-0.87167-0.0167-2.3259-1.2283-3.5316-1.2117-1.2056-2.6676-1.3141-3.5388-1.2128-0.87117 0.10126-1.2156 0.24786-2.1389-0.28215-0.92331-0.53002-0.9705-0.90044-1.3224-1.7038-0.3519-0.8033-1.1766-2.006-2.8288-2.4442-0.41304-0.10957-0.80507-0.15182-1.1715-0.14573z" fill="#336790" style="paint-order:markers fill stroke"/> + </g> + <g id="g1747" stroke-width=".22458"> + <g id="text1023" fill="#336790" aria-label="SETUP"> + <path id="path1713" d="m28.181 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1715" d="m32.036 126.47h4.4917v1.4036h-2.9944v1.9885h2.2458v1.4036h-2.2458v2.0353h2.9944v1.4036h-4.4917z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1717" d="m42.885 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1719" d="m43.627 126.47h1.4972v5.2403q0 0.54976 0.04094 0.74861 0.08773 0.42109 0.3743 0.67842 0.29242 0.25734 0.70767 0.25734t0.70182-0.25734q0.29242-0.25733 0.38015-0.67842 0.04094-0.19885 0.04094-0.74861v-5.2403h1.4972v5.2403q0 0.82464-0.09358 1.2223-0.19885 0.82463-0.88897 1.3452-0.68428 0.52052-1.6376 0.52052t-1.6434-0.52052q-0.68428-0.52052-0.88312-1.3452-0.09358-0.3977-0.09358-1.2223z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1721" d="m51.482 127.88v2.3862h0.36261q0.50297 0 0.73106-0.0468 0.3977-0.0819 0.63164-0.39185 0.23979-0.30997 0.23979-0.75446t-0.23979-0.75446q-0.23394-0.30997-0.63164-0.39185-0.22809-0.0468-0.73106-0.0468zm-1.4972-1.4036h1.8481q0.86558 0 1.234 0.0877 0.83049 0.19885 1.351 0.87143 0.52636 0.66673 0.52636 1.6376t-0.52636 1.6434q-0.52052 0.66673-1.351 0.86558-0.36846 0.0877-1.234 0.0877h-0.35091v3.0412h-1.4972z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + <g id="text1661" fill="#e5b62f" aria-label="TOOLS"> + <path id="path1724" d="m60.834 126.47v1.4036h-1.8715v6.831h-1.4972v-6.831h-1.8715v-1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1726" d="m63.068 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1728" d="m69.051 129.08q-0.08773 0.47958-0.08773 1.5089 0 1.0293 0.08773 1.5089 0.10527 0.5673 0.386 0.93576 0.28658 0.36261 0.74276 0.36261 0.45618 0 0.73691-0.36261 0.28658-0.36846 0.39185-0.93576 0.08773-0.48543 0.08773-1.5089 0-1.0293-0.08773-1.5089-0.10527-0.56731-0.39185-0.92991-0.28073-0.36846-0.73691-0.36846-0.45618 0-0.74276 0.36846-0.28073 0.3626-0.386 0.92991zm-1.4212 3.55q-0.16376-0.64918-0.16376-2.0411 0-1.3919 0.16376-2.0411 0.23394-0.94745 0.88312-1.5557 0.64918-0.61409 1.6668-0.61409 1.0176 0 1.6668 0.61409 0.64918 0.60825 0.88312 1.5557 0.16376 0.64919 0.16376 2.0411 0 1.392-0.16376 2.0411-0.23394 0.94746-0.88312 1.5616-0.64918 0.60825-1.6668 0.60825-1.0176 0-1.6668-0.60825-0.64918-0.61409-0.88312-1.5616z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1730" d="m73.917 134.71v-8.2347h1.4972v6.8311h3.3687v1.4036z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + <path id="path1732" d="m82.029 134.8q-0.95916 0-2.1639-0.18715v-1.427q1.4095 0.21055 2.1639 0.21055 1.041 0 1.041-1.1112 0-0.30997-0.15206-0.58485-0.14621-0.28073-0.41524-0.386-0.16961-0.0643-0.46788-0.10527-0.29827-0.0409-0.61409-0.11697-0.30997-0.0819-0.59655-0.25149-1.0995-0.65503-1.0995-2.0704 0-1.0118 0.64334-1.7019 0.64918-0.69012 1.661-0.69012 0.78955 0 2.1639 0.14621v1.4095q-1.4212-0.15206-2.1639-0.15206-0.22224 0-0.39185 0.0994-0.16376 0.0994-0.25149 0.25734-0.08773 0.15791-0.12867 0.32167-0.03509 0.16375-0.03509 0.32166 0 0.69013 0.46788 0.90067 0.15206 0.0702 0.69012 0.15791 0.54391 0.0819 0.87728 0.25734 0.46788 0.23979 0.772 0.61994 0.30412 0.38015 0.42109 0.76616 0.11697 0.386 0.11697 0.80124 0 1.1346-0.70182 1.8247-0.70182 0.69012-1.8364 0.69012z" style="font-feature-settings:normal;font-variant-caps:normal;font-variant-ligatures:normal;font-variant-numeric:normal"/> + </g> + </g> + </g> + </g> +</svg> diff --git a/docs/index.rst b/docs/index.rst index 325842bb..8328f87c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,35 @@ -Welcome to |project| documentation! -=================================== +.. image:: images/banner-640x320.svg + :align: center -.. toctree:: - :maxdepth: 1 +Documentation +============= - history +Setuptools is a fully-featured, actively-maintained, and stable library +designed to facilitate packaging Python projects. +It helps developers to easily share reusable code (in the form of a library) +and programs (e.g., CLI/GUI tools implemented in Python), that can be installed +with :pypi:`pip` and uploaded to `PyPI <http://pypi.org>`_. -.. automodule:: skeleton - :members: - :undoc-members: - :show-inheritance: +.. toctree:: + :maxdepth: 1 + :hidden: + User guide <userguide/index> + build_meta + pkg_resources + references/keywords + setuptools -Indices and tables -================== +.. toctree:: + :caption: Project + :maxdepth: 1 + :hidden: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + roadmap + Development guide <development/index> + Backward compatibility & deprecated practice <deprecated/index> + Changelog <history> + artwork +.. tidelift-referral-banner:: diff --git a/docs/pkg_resources.rst b/docs/pkg_resources.rst new file mode 100644 index 00000000..40e5e6f8 --- /dev/null +++ b/docs/pkg_resources.rst @@ -0,0 +1,1946 @@ +============================================================= +Package Discovery and Resource Access using ``pkg_resources`` +============================================================= + +The ``pkg_resources`` module distributed with ``setuptools`` provides an API +for Python libraries to access their resource files, and for extensible +applications and frameworks to automatically discover plugins. It also +provides runtime support for using C extensions that are inside zipfile-format +eggs, support for merging packages that have separately-distributed modules or +subpackages, and APIs for managing Python's current "working set" of active +packages. + +.. attention:: + Use of ``pkg_resources`` is discouraged in favor of + `importlib.resources <https://docs.python.org/3/library/importlib.html#module-importlib.resources>`_, + `importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_, + and their backports (:pypi:`importlib_resources`, + :pypi:`importlib_metadata`). + Please consider using those libraries instead of pkg_resources. + + +-------- +Overview +-------- + +The ``pkg_resources`` module provides runtime facilities for finding, +introspecting, activating and using installed Python distributions. Some +of the more advanced features (notably the support for parallel installation +of multiple versions) rely specifically on the "egg" format (either as a +zip archive or subdirectory), while others (such as plugin discovery) will +work correctly so long as "egg-info" metadata directories are available for +relevant distributions. + +Eggs are a distribution format for Python modules, similar in concept to +Java's "jars" or Ruby's "gems", or the "wheel" format defined in PEP 427. +However, unlike a pure distribution format, eggs can also be installed and +added directly to ``sys.path`` as an import location. When installed in +this way, eggs are *discoverable*, meaning that they carry metadata that +unambiguously identifies their contents and dependencies. This means that +an installed egg can be *automatically* found and added to ``sys.path`` in +response to simple requests of the form, "get me everything I need to use +docutils' PDF support". This feature allows mutually conflicting versions of +a distribution to co-exist in the same Python installation, with individual +applications activating the desired version at runtime by manipulating the +contents of ``sys.path`` (this differs from the virtual environment +approach, which involves creating isolated environments for each +application). + +The following terms are needed in order to explain the capabilities offered +by this module: + +project + A library, framework, script, plugin, application, or collection of data + or other resources, or some combination thereof. Projects are assumed to + have "relatively unique" names, e.g. names registered with PyPI. + +release + A snapshot of a project at a particular point in time, denoted by a version + identifier. + +distribution + A file or files that represent a particular release. + +importable distribution + A file or directory that, if placed on ``sys.path``, allows Python to + import any modules contained within it. + +pluggable distribution + An importable distribution whose filename unambiguously identifies its + release (i.e. project and version), and whose contents unambiguously + specify what releases of other projects will satisfy its runtime + requirements. + +extra + An "extra" is an optional feature of a release, that may impose additional + runtime requirements. For example, if docutils PDF support required a + PDF support library to be present, docutils could define its PDF support as + an "extra", and list what other project releases need to be available in + order to provide it. + +environment + A collection of distributions potentially available for importing, but not + necessarily active. More than one distribution (i.e. release version) for + a given project may be present in an environment. + +working set + A collection of distributions actually available for importing, as on + ``sys.path``. At most one distribution (release version) of a given + project may be present in a working set, as otherwise there would be + ambiguity as to what to import. + +eggs + Eggs are pluggable distributions in one of the three formats currently + supported by ``pkg_resources``. There are built eggs, development eggs, + and egg links. Built eggs are directories or zipfiles whose name ends + with ``.egg`` and follows the egg naming conventions, and contain an + ``EGG-INFO`` subdirectory (zipped or otherwise). Development eggs are + normal directories of Python code with one or more ``ProjectName.egg-info`` + subdirectories. The development egg format is also used to provide a + default version of a distribution that is available to software that + doesn't use ``pkg_resources`` to request specific versions. Egg links + are ``*.egg-link`` files that contain the name of a built or + development egg, to support symbolic linking on platforms that do not + have native symbolic links (or where the symbolic link support is + limited). + +(For more information about these terms and concepts, see also this +`architectural overview`_ of ``pkg_resources`` and Python Eggs in general.) + +.. _architectural overview: http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html + + +.. ----------------- +.. Developer's Guide +.. ----------------- + +.. This section isn't written yet. Currently planned topics include + Accessing Resources + Finding and Activating Package Distributions + get_provider() + require() + WorkingSet + iter_distributions + Running Scripts + Configuration + Namespace Packages + Extensible Applications and Frameworks + Locating entry points + Activation listeners + Metadata access + Extended Discovery and Installation + Supporting Custom PEP 302 Implementations +.. For now, please check out the extensive `API Reference`_ below. + + +------------- +API Reference +------------- + +Namespace Package Support +========================= + +A namespace package is a package that only contains other packages and modules, +with no direct contents of its own. Such packages can be split across +multiple, separately-packaged distributions. They are normally used to split +up large packages produced by a single organization, such as in the ``zope`` +namespace package for Zope Corporation packages, and the ``peak`` namespace +package for the Python Enterprise Application Kit. + +To create a namespace package, you list it in the ``namespace_packages`` +argument to ``setup()``, in your project's ``setup.py``. (See the +:ref:`setuptools documentation on namespace packages <Namespace Packages>` for +more information on this.) Also, you must add a ``declare_namespace()`` call +in the package's ``__init__.py`` file(s): + +``declare_namespace(name)`` + Declare that the dotted package name ``name`` is a "namespace package" whose + contained packages and modules may be spread across multiple distributions. + The named package's ``__path__`` will be extended to include the + corresponding package in all distributions on ``sys.path`` that contain a + package of that name. (More precisely, if an importer's + ``find_module(name)`` returns a loader, then it will also be searched for + the package's contents.) Whenever a Distribution's ``activate()`` method + is invoked, it checks for the presence of namespace packages and updates + their ``__path__`` contents accordingly. + +Applications that manipulate namespace packages or directly alter ``sys.path`` +at runtime may also need to use this API function: + +``fixup_namespace_packages(path_item)`` + Declare that ``path_item`` is a newly added item on ``sys.path`` that may + need to be used to update existing namespace packages. Ordinarily, this is + called for you when an egg is automatically added to ``sys.path``, but if + your application modifies ``sys.path`` to include locations that may + contain portions of a namespace package, you will need to call this + function to ensure they are added to the existing namespace packages. + +Although by default ``pkg_resources`` only supports namespace packages for +filesystem and zip importers, you can extend its support to other "importers" +compatible with PEP 302 using the ``register_namespace_handler()`` function. +See the section below on `Supporting Custom Importers`_ for details. + + +``WorkingSet`` Objects +====================== + +The ``WorkingSet`` class provides access to a collection of "active" +distributions. In general, there is only one meaningful ``WorkingSet`` +instance: the one that represents the distributions that are currently active +on ``sys.path``. This global instance is available under the name +``working_set`` in the ``pkg_resources`` module. However, specialized +tools may wish to manipulate working sets that don't correspond to +``sys.path``, and therefore may wish to create other ``WorkingSet`` instances. + +It's important to note that the global ``working_set`` object is initialized +from ``sys.path`` when ``pkg_resources`` is first imported, but is only updated +if you do all future ``sys.path`` manipulation via ``pkg_resources`` APIs. If +you manually modify ``sys.path``, you must invoke the appropriate methods on +the ``working_set`` instance to keep it in sync. Unfortunately, Python does +not provide any way to detect arbitrary changes to a list object like +``sys.path``, so ``pkg_resources`` cannot automatically update the +``working_set`` based on changes to ``sys.path``. + +``WorkingSet(entries=None)`` + Create a ``WorkingSet`` from an iterable of path entries. If ``entries`` + is not supplied, it defaults to the value of ``sys.path`` at the time + the constructor is called. + + Note that you will not normally construct ``WorkingSet`` instances + yourself, but instead you will implicitly or explicitly use the global + ``working_set`` instance. For the most part, the ``pkg_resources`` API + is designed so that the ``working_set`` is used by default, such that you + don't have to explicitly refer to it most of the time. + +All distributions available directly on ``sys.path`` will be activated +automatically when ``pkg_resources`` is imported. This behaviour can cause +version conflicts for applications which require non-default versions of +those distributions. To handle this situation, ``pkg_resources`` checks for a +``__requires__`` attribute in the ``__main__`` module when initializing the +default working set, and uses this to ensure a suitable version of each +affected distribution is activated. For example:: + + __requires__ = ["CherryPy < 3"] # Must be set before pkg_resources import + import pkg_resources + + +Basic ``WorkingSet`` Methods +---------------------------- + +The following methods of ``WorkingSet`` objects are also available as module- +level functions in ``pkg_resources`` that apply to the default ``working_set`` +instance. Thus, you can use e.g. ``pkg_resources.require()`` as an +abbreviation for ``pkg_resources.working_set.require()``: + + +``require(*requirements)`` + Ensure that distributions matching ``requirements`` are activated + + ``requirements`` must be a string or a (possibly-nested) sequence + thereof, specifying the distributions and versions required. The + return value is a sequence of the distributions that needed to be + activated to fulfill the requirements; all relevant distributions are + included, even if they were already activated in this working set. + + For the syntax of requirement specifiers, see the section below on + `Requirements Parsing`_. + + In general, it should not be necessary for you to call this method + directly. It's intended more for use in quick-and-dirty scripting and + interactive interpreter hacking than for production use. If you're creating + an actual library or application, it's strongly recommended that you create + a "setup.py" script using ``setuptools``, and declare all your requirements + there. That way, tools like pip can automatically detect what requirements + your package has, and deal with them accordingly. + + Note that calling ``require('SomePackage')`` will not install + ``SomePackage`` if it isn't already present. If you need to do this, you + should use the ``resolve()`` method instead, which allows you to pass an + ``installer`` callback that will be invoked when a needed distribution + can't be found on the local machine. You can then have this callback + display a dialog, automatically download the needed distribution, or + whatever else is appropriate for your application. See the documentation + below on the ``resolve()`` method for more information, and also on the + ``obtain()`` method of ``Environment`` objects. + +``run_script(requires, script_name)`` + Locate distribution specified by ``requires`` and run its ``script_name`` + script. ``requires`` must be a string containing a requirement specifier. + (See `Requirements Parsing`_ below for the syntax.) + + The script, if found, will be executed in *the caller's globals*. That's + because this method is intended to be called from wrapper scripts that + act as a proxy for the "real" scripts in a distribution. A wrapper script + usually doesn't need to do anything but invoke this function with the + correct arguments. + + If you need more control over the script execution environment, you + probably want to use the ``run_script()`` method of a ``Distribution`` + object's `Metadata API`_ instead. + +``iter_entry_points(group, name=None)`` + Yield entry point objects from ``group`` matching ``name`` + + If ``name`` is None, yields all entry points in ``group`` from all + distributions in the working set, otherwise only ones matching both + ``group`` and ``name`` are yielded. Entry points are yielded from the active + distributions in the order that the distributions appear in the working + set. (For the global ``working_set``, this should be the same as the order + that they are listed in ``sys.path``.) Note that within the entry points + advertised by an individual distribution, there is no particular ordering. + + Please see the section below on `Entry Points`_ for more information. + + +``WorkingSet`` Methods and Attributes +------------------------------------- + +These methods are used to query or manipulate the contents of a specific +working set, so they must be explicitly invoked on a particular ``WorkingSet`` +instance: + +``add_entry(entry)`` + Add a path item to the ``entries``, finding any distributions on it. You + should use this when you add additional items to ``sys.path`` and you want + the global ``working_set`` to reflect the change. This method is also + called by the ``WorkingSet()`` constructor during initialization. + + This method uses ``find_distributions(entry,True)`` to find distributions + corresponding to the path entry, and then ``add()`` them. ``entry`` is + always appended to the ``entries`` attribute, even if it is already + present, however. (This is because ``sys.path`` can contain the same value + more than once, and the ``entries`` attribute should be able to reflect + this.) + +``__contains__(dist)`` + True if ``dist`` is active in this ``WorkingSet``. Note that only one + distribution for a given project can be active in a given ``WorkingSet``. + +``__iter__()`` + Yield distributions for non-duplicate projects in the working set. + The yield order is the order in which the items' path entries were + added to the working set. + +``find(req)`` + Find a distribution matching ``req`` (a ``Requirement`` instance). + If there is an active distribution for the requested project, this + returns it, as long as it meets the version requirement specified by + ``req``. But, if there is an active distribution for the project and it + does *not* meet the ``req`` requirement, ``VersionConflict`` is raised. + If there is no active distribution for the requested project, ``None`` + is returned. + +``resolve(requirements, env=None, installer=None)`` + List all distributions needed to (recursively) meet ``requirements`` + + ``requirements`` must be a sequence of ``Requirement`` objects. ``env``, + if supplied, should be an ``Environment`` instance. If + not supplied, an ``Environment`` is created from the working set's + ``entries``. ``installer``, if supplied, will be invoked with each + requirement that cannot be met by an already-installed distribution; it + should return a ``Distribution`` or ``None``. (See the ``obtain()`` method + of `Environment Objects`_, below, for more information on the ``installer`` + argument.) + +``add(dist, entry=None)`` + Add ``dist`` to working set, associated with ``entry`` + + If ``entry`` is unspecified, it defaults to ``dist.location``. On exit from + this routine, ``entry`` is added to the end of the working set's ``.entries`` + (if it wasn't already present). + + ``dist`` is only added to the working set if it's for a project that + doesn't already have a distribution active in the set. If it's + successfully added, any callbacks registered with the ``subscribe()`` + method will be called. (See `Receiving Change Notifications`_, below.) + + Note: ``add()`` is automatically called for you by the ``require()`` + method, so you don't normally need to use this method directly. + +``entries`` + This attribute represents a "shadow" ``sys.path``, primarily useful for + debugging. If you are experiencing import problems, you should check + the global ``working_set`` object's ``entries`` against ``sys.path``, to + ensure that they match. If they do not, then some part of your program + is manipulating ``sys.path`` without updating the ``working_set`` + accordingly. IMPORTANT NOTE: do not directly manipulate this attribute! + Setting it equal to ``sys.path`` will not fix your problem, any more than + putting black tape over an "engine warning" light will fix your car! If + this attribute is out of sync with ``sys.path``, it's merely an *indicator* + of the problem, not the cause of it. + + +Receiving Change Notifications +------------------------------ + +Extensible applications and frameworks may need to receive notification when +a new distribution (such as a plug-in component) has been added to a working +set. This is what the ``subscribe()`` method and ``add_activation_listener()`` +function are for. + +``subscribe(callback)`` + Invoke ``callback(distribution)`` once for each active distribution that is + in the set now, or gets added later. Because the callback is invoked for + already-active distributions, you do not need to loop over the working set + yourself to deal with the existing items; just register the callback and + be prepared for the fact that it will be called immediately by this method. + + Note that callbacks *must not* allow exceptions to propagate, or they will + interfere with the operation of other callbacks and possibly result in an + inconsistent working set state. Callbacks should use a try/except block + to ignore, log, or otherwise process any errors, especially since the code + that caused the callback to be invoked is unlikely to be able to handle + the errors any better than the callback itself. + +``pkg_resources.add_activation_listener()`` is an alternate spelling of +``pkg_resources.working_set.subscribe()``. + + +Locating Plugins +---------------- + +Extensible applications will sometimes have a "plugin directory" or a set of +plugin directories, from which they want to load entry points or other +metadata. The ``find_plugins()`` method allows you to do this, by scanning an +environment for the newest version of each project that can be safely loaded +without conflicts or missing requirements. + +``find_plugins(plugin_env, full_env=None, fallback=True)`` + Scan ``plugin_env`` and identify which distributions could be added to this + working set without version conflicts or missing requirements. + + Example usage:: + + distributions, errors = working_set.find_plugins( + Environment(plugin_dirlist) + ) + map(working_set.add, distributions) # add plugins+libs to sys.path + print "Couldn't load", errors # display errors + + The ``plugin_env`` should be an ``Environment`` instance that contains only + distributions that are in the project's "plugin directory" or directories. + The ``full_env``, if supplied, should be an ``Environment`` instance that + contains all currently-available distributions. + + If ``full_env`` is not supplied, one is created automatically from the + ``WorkingSet`` this method is called on, which will typically mean that + every directory on ``sys.path`` will be scanned for distributions. + + This method returns a 2-tuple: (``distributions``, ``error_info``), where + ``distributions`` is a list of the distributions found in ``plugin_env`` that + were loadable, along with any other distributions that are needed to resolve + their dependencies. ``error_info`` is a dictionary mapping unloadable plugin + distributions to an exception instance describing the error that occurred. + Usually this will be a ``DistributionNotFound`` or ``VersionConflict`` + instance. + + Most applications will use this method mainly on the master ``working_set`` + instance in ``pkg_resources``, and then immediately add the returned + distributions to the working set so that they are available on sys.path. + This will make it possible to find any entry points, and allow any other + metadata tracking and hooks to be activated. + + The resolution algorithm used by ``find_plugins()`` is as follows. First, + the project names of the distributions present in ``plugin_env`` are sorted. + Then, each project's eggs are tried in descending version order (i.e., + newest version first). + + An attempt is made to resolve each egg's dependencies. If the attempt is + successful, the egg and its dependencies are added to the output list and to + a temporary copy of the working set. The resolution process continues with + the next project name, and no older eggs for that project are tried. + + If the resolution attempt fails, however, the error is added to the error + dictionary. If the ``fallback`` flag is true, the next older version of the + plugin is tried, until a working version is found. If false, the resolution + process continues with the next plugin project name. + + Some applications may have stricter fallback requirements than others. For + example, an application that has a database schema or persistent objects + may not be able to safely downgrade a version of a package. Others may want + to ensure that a new plugin configuration is either 100% good or else + revert to a known-good configuration. (That is, they may wish to revert to + a known configuration if the ``error_info`` return value is non-empty.) + + Note that this algorithm gives precedence to satisfying the dependencies of + alphabetically prior project names in case of version conflicts. If two + projects named "AaronsPlugin" and "ZekesPlugin" both need different versions + of "TomsLibrary", then "AaronsPlugin" will win and "ZekesPlugin" will be + disabled due to version conflict. + + +``Environment`` Objects +======================= + +An "environment" is a collection of ``Distribution`` objects, usually ones +that are present and potentially importable on the current platform. +``Environment`` objects are used by ``pkg_resources`` to index available +distributions during dependency resolution. + +``Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)`` + Create an environment snapshot by scanning ``search_path`` for distributions + compatible with ``platform`` and ``python``. ``search_path`` should be a + sequence of strings such as might be used on ``sys.path``. If a + ``search_path`` isn't supplied, ``sys.path`` is used. + + ``platform`` is an optional string specifying the name of the platform + that platform-specific distributions must be compatible with. If + unspecified, it defaults to the current platform. ``python`` is an + optional string naming the desired version of Python (e.g. ``'2.4'``); + it defaults to the currently-running version. + + You may explicitly set ``platform`` (and/or ``python``) to ``None`` if you + wish to include *all* distributions, not just those compatible with the + running platform or Python version. + + Note that ``search_path`` is scanned immediately for distributions, and the + resulting ``Environment`` is a snapshot of the found distributions. It + is not automatically updated if the system's state changes due to e.g. + installation or removal of distributions. + +``__getitem__(project_name)`` + Returns a list of distributions for the given project name, ordered + from newest to oldest version. (And highest to lowest format precedence + for distributions that contain the same version of the project.) If there + are no distributions for the project, returns an empty list. + +``__iter__()`` + Yield the unique project names of the distributions in this environment. + The yielded names are always in lower case. + +``add(dist)`` + Add ``dist`` to the environment if it matches the platform and python version + specified at creation time, and only if the distribution hasn't already + been added. (i.e., adding the same distribution more than once is a no-op.) + +``remove(dist)`` + Remove ``dist`` from the environment. + +``can_add(dist)`` + Is distribution ``dist`` acceptable for this environment? If it's not + compatible with the ``platform`` and ``python`` version values specified + when the environment was created, a false value is returned. + +``__add__(dist_or_env)`` (``+`` operator) + Add a distribution or environment to an ``Environment`` instance, returning + a *new* environment object that contains all the distributions previously + contained by both. The new environment will have a ``platform`` and + ``python`` of ``None``, meaning that it will not reject any distributions + from being added to it; it will simply accept whatever is added. If you + want the added items to be filtered for platform and Python version, or + you want to add them to the *same* environment instance, you should use + in-place addition (``+=``) instead. + +``__iadd__(dist_or_env)`` (``+=`` operator) + Add a distribution or environment to an ``Environment`` instance + *in-place*, updating the existing instance and returning it. The + ``platform`` and ``python`` filter attributes take effect, so distributions + in the source that do not have a suitable platform string or Python version + are silently ignored. + +``best_match(req, working_set, installer=None)`` + Find distribution best matching ``req`` and usable on ``working_set`` + + This calls the ``find(req)`` method of the ``working_set`` to see if a + suitable distribution is already active. (This may raise + ``VersionConflict`` if an unsuitable version of the project is already + active in the specified ``working_set``.) If a suitable distribution isn't + active, this method returns the newest distribution in the environment + that meets the ``Requirement`` in ``req``. If no suitable distribution is + found, and ``installer`` is supplied, then the result of calling + the environment's ``obtain(req, installer)`` method will be returned. + +``obtain(requirement, installer=None)`` + Obtain a distro that matches requirement (e.g. via download). In the + base ``Environment`` class, this routine just returns + ``installer(requirement)``, unless ``installer`` is None, in which case + None is returned instead. This method is a hook that allows subclasses + to attempt other ways of obtaining a distribution before falling back + to the ``installer`` argument. + +``scan(search_path=None)`` + Scan ``search_path`` for distributions usable on ``platform`` + + Any distributions found are added to the environment. ``search_path`` should + be a sequence of strings such as might be used on ``sys.path``. If not + supplied, ``sys.path`` is used. Only distributions conforming to + the platform/python version defined at initialization are added. This + method is a shortcut for using the ``find_distributions()`` function to + find the distributions from each item in ``search_path``, and then calling + ``add()`` to add each one to the environment. + + +``Requirement`` Objects +======================= + +``Requirement`` objects express what versions of a project are suitable for +some purpose. These objects (or their string form) are used by various +``pkg_resources`` APIs in order to find distributions that a script or +distribution needs. + + +Requirements Parsing +-------------------- + +``parse_requirements(s)`` + Yield ``Requirement`` objects for a string or iterable of lines. Each + requirement must start on a new line. See below for syntax. + +``Requirement.parse(s)`` + Create a ``Requirement`` object from a string or iterable of lines. A + ``ValueError`` is raised if the string or lines do not contain a valid + requirement specifier, or if they contain more than one specifier. (To + parse multiple specifiers from a string or iterable of strings, use + ``parse_requirements()`` instead.) + + The syntax of a requirement specifier is defined in full in PEP 508. + + Some examples of valid requirement specifiers:: + + FooProject >= 1.2 + Fizzy [foo, bar] + PickyThing>1.6,<=1.9,!=1.8.6 + SomethingWhoseVersionIDontCareAbout + SomethingWithMarker[foo]>1.0;python_version<"2.7" + + The project name is the only required portion of a requirement string, and + if it's the only thing supplied, the requirement will accept any version + of that project. + + The "extras" in a requirement are used to request optional features of a + project, that may require additional project distributions in order to + function. For example, if the hypothetical "Report-O-Rama" project offered + optional PDF support, it might require an additional library in order to + provide that support. Thus, a project needing Report-O-Rama's PDF features + could use a requirement of ``Report-O-Rama[PDF]`` to request installation + or activation of both Report-O-Rama and any libraries it needs in order to + provide PDF support. For example, you could use:: + + pip install Report-O-Rama[PDF] + + To install the necessary packages using pip, or call + ``pkg_resources.require('Report-O-Rama[PDF]')`` to add the necessary + distributions to sys.path at runtime. + + The "markers" in a requirement are used to specify when a requirement + should be installed -- the requirement will be installed if the marker + evaluates as true in the current environment. For example, specifying + ``argparse;python_version<"3.0"`` will not install in an Python 3 + environment, but will in a Python 2 environment. + +``Requirement`` Methods and Attributes +-------------------------------------- + +``__contains__(dist_or_version)`` + Return true if ``dist_or_version`` fits the criteria for this requirement. + If ``dist_or_version`` is a ``Distribution`` object, its project name must + match the requirement's project name, and its version must meet the + requirement's version criteria. If ``dist_or_version`` is a string, it is + parsed using the ``parse_version()`` utility function. Otherwise, it is + assumed to be an already-parsed version. + + The ``Requirement`` object's version specifiers (``.specs``) are internally + sorted into ascending version order, and used to establish what ranges of + versions are acceptable. Adjacent redundant conditions are effectively + consolidated (e.g. ``">1, >2"`` produces the same results as ``">2"``, and + ``"<2,<3"`` produces the same results as ``"<2"``). ``"!="`` versions are + excised from the ranges they fall within. The version being tested for + acceptability is then checked for membership in the resulting ranges. + +``__eq__(other_requirement)`` + A requirement compares equal to another requirement if they have + case-insensitively equal project names, version specifiers, and "extras". + (The order that extras and version specifiers are in is also ignored.) + Equal requirements also have equal hashes, so that requirements can be + used in sets or as dictionary keys. + +``__str__()`` + The string form of a ``Requirement`` is a string that, if passed to + ``Requirement.parse()``, would return an equal ``Requirement`` object. + +``project_name`` + The name of the required project + +``key`` + An all-lowercase version of the ``project_name``, useful for comparison + or indexing. + +``extras`` + A tuple of names of "extras" that this requirement calls for. (These will + be all-lowercase and normalized using the ``safe_extra()`` parsing utility + function, so they may not exactly equal the extras the requirement was + created with.) + +``specs`` + A list of ``(op,version)`` tuples, sorted in ascending parsed-version + order. The ``op`` in each tuple is a comparison operator, represented as + a string. The ``version`` is the (unparsed) version number. + +``marker`` + An instance of ``packaging.markers.Marker`` that allows evaluation + against the current environment. May be None if no marker specified. + +``url`` + The location to download the requirement from if specified. + +Entry Points +============ + +Entry points are a simple way for distributions to "advertise" Python objects +(such as functions or classes) for use by other distributions. Extensible +applications and frameworks can search for entry points with a particular name +or group, either from a specific distribution or from all active distributions +on sys.path, and then inspect or load the advertised objects at will. + +Entry points belong to "groups" which are named with a dotted name similar to +a Python package or module name. For example, the ``setuptools`` package uses +an entry point named ``distutils.commands`` in order to find commands defined +by distutils extensions. ``setuptools`` treats the names of entry points +defined in that group as the acceptable commands for a setup script. + +In a similar way, other packages can define their own entry point groups, +either using dynamic names within the group (like ``distutils.commands``), or +possibly using predefined names within the group. For example, a blogging +framework that offers various pre- or post-publishing hooks might define an +entry point group and look for entry points named "pre_process" and +"post_process" within that group. + +To advertise an entry point, a project needs to use ``setuptools`` and provide +an ``entry_points`` argument to ``setup()`` in its setup script, so that the +entry points will be included in the distribution's metadata. For more +details, see :ref:`Advertising Behavior<dynamic discovery of services and plugins>`. + +Each project distribution can advertise at most one entry point of a given +name within the same entry point group. For example, a distutils extension +could advertise two different ``distutils.commands`` entry points, as long as +they had different names. However, there is nothing that prevents *different* +projects from advertising entry points of the same name in the same group. In +some cases, this is a desirable thing, since the application or framework that +uses the entry points may be calling them as hooks, or in some other way +combining them. It is up to the application or framework to decide what to do +if multiple distributions advertise an entry point; some possibilities include +using both entry points, displaying an error message, using the first one found +in sys.path order, etc. + + +Convenience API +--------------- + +In the following functions, the ``dist`` argument can be a ``Distribution`` +instance, a ``Requirement`` instance, or a string specifying a requirement +(i.e. project name, version, etc.). If the argument is a string or +``Requirement``, the specified distribution is located (and added to sys.path +if not already present). An error will be raised if a matching distribution is +not available. + +The ``group`` argument should be a string containing a dotted identifier, +identifying an entry point group. If you are defining an entry point group, +you should include some portion of your package's name in the group name so as +to avoid collision with other packages' entry point groups. + +``load_entry_point(dist, group, name)`` + Load the named entry point from the specified distribution, or raise + ``ImportError``. + +``get_entry_info(dist, group, name)`` + Return an ``EntryPoint`` object for the given ``group`` and ``name`` from + the specified distribution. Returns ``None`` if the distribution has not + advertised a matching entry point. + +``get_entry_map(dist, group=None)`` + Return the distribution's entry point map for ``group``, or the full entry + map for the distribution. This function always returns a dictionary, + even if the distribution advertises no entry points. If ``group`` is given, + the dictionary maps entry point names to the corresponding ``EntryPoint`` + object. If ``group`` is None, the dictionary maps group names to + dictionaries that then map entry point names to the corresponding + ``EntryPoint`` instance in that group. + +``iter_entry_points(group, name=None)`` + Yield entry point objects from ``group`` matching ``name``. + + If ``name`` is None, yields all entry points in ``group`` from all + distributions in the working set on sys.path, otherwise only ones matching + both ``group`` and ``name`` are yielded. Entry points are yielded from + the active distributions in the order that the distributions appear on + sys.path. (Within entry points for a particular distribution, however, + there is no particular ordering.) + + (This API is actually a method of the global ``working_set`` object; see + the section above on `Basic WorkingSet Methods`_ for more information.) + + +Creating and Parsing +-------------------- + +``EntryPoint(name, module_name, attrs=(), extras=(), dist=None)`` + Create an ``EntryPoint`` instance. ``name`` is the entry point name. The + ``module_name`` is the (dotted) name of the module containing the advertised + object. ``attrs`` is an optional tuple of names to look up from the + module to obtain the advertised object. For example, an ``attrs`` of + ``("foo","bar")`` and a ``module_name`` of ``"baz"`` would mean that the + advertised object could be obtained by the following code:: + + import baz + advertised_object = baz.foo.bar + + The ``extras`` are an optional tuple of "extra feature" names that the + distribution needs in order to provide this entry point. When the + entry point is loaded, these extra features are looked up in the ``dist`` + argument to find out what other distributions may need to be activated + on sys.path; see the ``load()`` method for more details. The ``extras`` + argument is only meaningful if ``dist`` is specified. ``dist`` must be + a ``Distribution`` instance. + +``EntryPoint.parse(src, dist=None)`` (classmethod) + Parse a single entry point from string ``src`` + + Entry point syntax follows the form:: + + name = some.module:some.attr [extra1,extra2] + + The entry name and module name are required, but the ``:attrs`` and + ``[extras]`` parts are optional, as is the whitespace shown between + some of the items. The ``dist`` argument is passed through to the + ``EntryPoint()`` constructor, along with the other values parsed from + ``src``. + +``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod) + Parse ``lines`` (a string or sequence of lines) to create a dictionary + mapping entry point names to ``EntryPoint`` objects. ``ValueError`` is + raised if entry point names are duplicated, if ``group`` is not a valid + entry point group name, or if there are any syntax errors. (Note: the + ``group`` parameter is used only for validation and to create more + informative error messages.) If ``dist`` is provided, it will be used to + set the ``dist`` attribute of the created ``EntryPoint`` objects. + +``EntryPoint.parse_map(data, dist=None)`` (classmethod) + Parse ``data`` into a dictionary mapping group names to dictionaries mapping + entry point names to ``EntryPoint`` objects. If ``data`` is a dictionary, + then the keys are used as group names and the values are passed to + ``parse_group()`` as the ``lines`` argument. If ``data`` is a string or + sequence of lines, it is first split into .ini-style sections (using + the ``split_sections()`` utility function) and the section names are used + as group names. In either case, the ``dist`` argument is passed through to + ``parse_group()`` so that the entry points will be linked to the specified + distribution. + + +``EntryPoint`` Objects +---------------------- + +For simple introspection, ``EntryPoint`` objects have attributes that +correspond exactly to the constructor argument names: ``name``, +``module_name``, ``attrs``, ``extras``, and ``dist`` are all available. In +addition, the following methods are provided: + +``load()`` + Load the entry point, returning the advertised Python object. Effectively + calls ``self.require()`` then returns ``self.resolve()``. + +``require(env=None, installer=None)`` + Ensure that any "extras" needed by the entry point are available on + sys.path. ``UnknownExtra`` is raised if the ``EntryPoint`` has ``extras``, + but no ``dist``, or if the named extras are not defined by the + distribution. If ``env`` is supplied, it must be an ``Environment``, and it + will be used to search for needed distributions if they are not already + present on sys.path. If ``installer`` is supplied, it must be a callable + taking a ``Requirement`` instance and returning a matching importable + ``Distribution`` instance or None. + +``resolve()`` + Resolve the entry point from its module and attrs, returning the advertised + Python object. Raises ``ImportError`` if it cannot be obtained. + +``__str__()`` + The string form of an ``EntryPoint`` is a string that could be passed to + ``EntryPoint.parse()`` to produce an equivalent ``EntryPoint``. + + +``Distribution`` Objects +======================== + +``Distribution`` objects represent collections of Python code that may or may +not be importable, and may or may not have metadata and resources associated +with them. Their metadata may include information such as what other projects +the distribution depends on, what entry points the distribution advertises, and +so on. + + +Getting or Creating Distributions +--------------------------------- + +Most commonly, you'll obtain ``Distribution`` objects from a ``WorkingSet`` or +an ``Environment``. (See the sections above on `WorkingSet Objects`_ and +`Environment Objects`_, which are containers for active distributions and +available distributions, respectively.) You can also obtain ``Distribution`` +objects from one of these high-level APIs: + +``find_distributions(path_item, only=False)`` + Yield distributions accessible via ``path_item``. If ``only`` is true, yield + only distributions whose ``location`` is equal to ``path_item``. In other + words, if ``only`` is true, this yields any distributions that would be + importable if ``path_item`` were on ``sys.path``. If ``only`` is false, this + also yields distributions that are "in" or "under" ``path_item``, but would + not be importable unless their locations were also added to ``sys.path``. + +``get_distribution(dist_spec)`` + Return a ``Distribution`` object for a given ``Requirement`` or string. + If ``dist_spec`` is already a ``Distribution`` instance, it is returned. + If it is a ``Requirement`` object or a string that can be parsed into one, + it is used to locate and activate a matching distribution, which is then + returned. + +However, if you're creating specialized tools for working with distributions, +or creating a new distribution format, you may also need to create +``Distribution`` objects directly, using one of the three constructors below. + +These constructors all take an optional ``metadata`` argument, which is used to +access any resources or metadata associated with the distribution. ``metadata`` +must be an object that implements the ``IResourceProvider`` interface, or None. +If it is None, an ``EmptyProvider`` is used instead. ``Distribution`` objects +implement both the `IResourceProvider`_ and `IMetadataProvider Methods`_ by +delegating them to the ``metadata`` object. + +``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod) + Create a distribution for ``location``, which must be a string such as a + URL, filename, or other string that might be used on ``sys.path``. + ``basename`` is a string naming the distribution, like ``Foo-1.2-py2.4.egg``. + If ``basename`` ends with ``.egg``, then the project's name, version, python + version and platform are extracted from the filename and used to set those + properties of the created distribution. Any additional keyword arguments + are forwarded to the ``Distribution()`` constructor. + +``Distribution.from_filename(filename, metadata=None**kw)`` (classmethod) + Create a distribution by parsing a local filename. This is a shorter way + of saying ``Distribution.from_location(normalize_path(filename), + os.path.basename(filename), metadata)``. In other words, it creates a + distribution whose location is the normalize form of the filename, parsing + name and version information from the base portion of the filename. Any + additional keyword arguments are forwarded to the ``Distribution()`` + constructor. + +``Distribution(location,metadata,project_name,version,py_version,platform,precedence)`` + Create a distribution by setting its properties. All arguments are + optional and default to None, except for ``py_version`` (which defaults to + the current Python version) and ``precedence`` (which defaults to + ``EGG_DIST``; for more details see ``precedence`` under `Distribution + Attributes`_ below). Note that it's usually easier to use the + ``from_filename()`` or ``from_location()`` constructors than to specify + all these arguments individually. + + +``Distribution`` Attributes +--------------------------- + +location + A string indicating the distribution's location. For an importable + distribution, this is the string that would be added to ``sys.path`` to + make it actively importable. For non-importable distributions, this is + simply a filename, URL, or other way of locating the distribution. + +project_name + A string, naming the project that this distribution is for. Project names + are defined by a project's setup script, and they are used to identify + projects on PyPI. When a ``Distribution`` is constructed, the + ``project_name`` argument is passed through the ``safe_name()`` utility + function to filter out any unacceptable characters. + +key + ``dist.key`` is short for ``dist.project_name.lower()``. It's used for + case-insensitive comparison and indexing of distributions by project name. + +extras + A list of strings, giving the names of extra features defined by the + project's dependency list (the ``extras_require`` argument specified in + the project's setup script). + +version + A string denoting what release of the project this distribution contains. + When a ``Distribution`` is constructed, the ``version`` argument is passed + through the ``safe_version()`` utility function to filter out any + unacceptable characters. If no ``version`` is specified at construction + time, then attempting to access this attribute later will cause the + ``Distribution`` to try to discover its version by reading its ``PKG-INFO`` + metadata file. If ``PKG-INFO`` is unavailable or can't be parsed, + ``ValueError`` is raised. + +parsed_version + The ``parsed_version`` is an object representing a "parsed" form of the + distribution's ``version``. ``dist.parsed_version`` is a shortcut for + calling ``parse_version(dist.version)``. It is used to compare or sort + distributions by version. (See the `Parsing Utilities`_ section below for + more information on the ``parse_version()`` function.) Note that accessing + ``parsed_version`` may result in a ``ValueError`` if the ``Distribution`` + was constructed without a ``version`` and without ``metadata`` capable of + supplying the missing version info. + +py_version + The major/minor Python version the distribution supports, as a string. + For example, "2.7" or "3.4". The default is the current version of Python. + +platform + A string representing the platform the distribution is intended for, or + ``None`` if the distribution is "pure Python" and therefore cross-platform. + See `Platform Utilities`_ below for more information on platform strings. + +precedence + A distribution's ``precedence`` is used to determine the relative order of + two distributions that have the same ``project_name`` and + ``parsed_version``. The default precedence is ``pkg_resources.EGG_DIST``, + which is the highest (i.e. most preferred) precedence. The full list + of predefined precedences, from most preferred to least preferred, is: + ``EGG_DIST``, ``BINARY_DIST``, ``SOURCE_DIST``, ``CHECKOUT_DIST``, and + ``DEVELOP_DIST``. Normally, precedences other than ``EGG_DIST`` are used + only by the ``setuptools.package_index`` module, when sorting distributions + found in a package index to determine their suitability for installation. + "System" and "Development" eggs (i.e., ones that use the ``.egg-info`` + format), however, are automatically given a precedence of ``DEVELOP_DIST``. + + + +``Distribution`` Methods +------------------------ + +``activate(path=None)`` + Ensure distribution is importable on ``path``. If ``path`` is None, + ``sys.path`` is used instead. This ensures that the distribution's + ``location`` is in the ``path`` list, and it also performs any necessary + namespace package fixups or declarations. (That is, if the distribution + contains namespace packages, this method ensures that they are declared, + and that the distribution's contents for those namespace packages are + merged with the contents provided by any other active distributions. See + the section above on `Namespace Package Support`_ for more information.) + + ``pkg_resources`` adds a notification callback to the global ``working_set`` + that ensures this method is called whenever a distribution is added to it. + Therefore, you should not normally need to explicitly call this method. + (Note that this means that namespace packages on ``sys.path`` are always + imported as soon as ``pkg_resources`` is, which is another reason why + namespace packages should not contain any code or import statements.) + +``as_requirement()`` + Return a ``Requirement`` instance that matches this distribution's project + name and version. + +``requires(extras=())`` + List the ``Requirement`` objects that specify this distribution's + dependencies. If ``extras`` is specified, it should be a sequence of names + of "extras" defined by the distribution, and the list returned will then + include any dependencies needed to support the named "extras". + +``clone(**kw)`` + Create a copy of the distribution. Any supplied keyword arguments override + the corresponding argument to the ``Distribution()`` constructor, allowing + you to change some of the copied distribution's attributes. + +``egg_name()`` + Return what this distribution's standard filename should be, not including + the ".egg" extension. For example, a distribution for project "Foo" + version 1.2 that runs on Python 2.3 for Windows would have an ``egg_name()`` + of ``Foo-1.2-py2.3-win32``. Any dashes in the name or version are + converted to underscores. (``Distribution.from_location()`` will convert + them back when parsing a ".egg" file name.) + +``__cmp__(other)``, ``__hash__()`` + Distribution objects are hashed and compared on the basis of their parsed + version and precedence, followed by their key (lowercase project name), + location, Python version, and platform. + +The following methods are used to access ``EntryPoint`` objects advertised +by the distribution. See the section above on `Entry Points`_ for more +detailed information about these operations: + +``get_entry_info(group, name)`` + Return the ``EntryPoint`` object for ``group`` and ``name``, or None if no + such point is advertised by this distribution. + +``get_entry_map(group=None)`` + Return the entry point map for ``group``. If ``group`` is None, return + a dictionary mapping group names to entry point maps for all groups. + (An entry point map is a dictionary of entry point names to ``EntryPoint`` + objects.) + +``load_entry_point(group, name)`` + Short for ``get_entry_info(group, name).load()``. Returns the object + advertised by the named entry point, or raises ``ImportError`` if + the entry point isn't advertised by this distribution, or there is some + other import problem. + +In addition to the above methods, ``Distribution`` objects also implement all +of the `IResourceProvider`_ and `IMetadataProvider Methods`_ (which are +documented in later sections): + +* ``has_metadata(name)`` +* ``metadata_isdir(name)`` +* ``metadata_listdir(name)`` +* ``get_metadata(name)`` +* ``get_metadata_lines(name)`` +* ``run_script(script_name, namespace)`` +* ``get_resource_filename(manager, resource_name)`` +* ``get_resource_stream(manager, resource_name)`` +* ``get_resource_string(manager, resource_name)`` +* ``has_resource(resource_name)`` +* ``resource_isdir(resource_name)`` +* ``resource_listdir(resource_name)`` + +If the distribution was created with a ``metadata`` argument, these resource and +metadata access methods are all delegated to that ``metadata`` provider. +Otherwise, they are delegated to an ``EmptyProvider``, so that the distribution +will appear to have no resources or metadata. This delegation approach is used +so that supporting custom importers or new distribution formats can be done +simply by creating an appropriate `IResourceProvider`_ implementation; see the +section below on `Supporting Custom Importers`_ for more details. + +.. _ResourceManager API: + +``ResourceManager`` API +======================= + +The ``ResourceManager`` class provides uniform access to package resources, +whether those resources exist as files and directories or are compressed in +an archive of some kind. + +Normally, you do not need to create or explicitly manage ``ResourceManager`` +instances, as the ``pkg_resources`` module creates a global instance for you, +and makes most of its methods available as top-level names in the +``pkg_resources`` module namespace. So, for example, this code actually +calls the ``resource_string()`` method of the global ``ResourceManager``:: + + import pkg_resources + my_data = pkg_resources.resource_string(__name__, "foo.dat") + +Thus, you can use the APIs below without needing an explicit +``ResourceManager`` instance; just import and use them as needed. + + +Basic Resource Access +--------------------- + +In the following methods, the ``package_or_requirement`` argument may be either +a Python package/module name (e.g. ``foo.bar``) or a ``Requirement`` instance. +If it is a package or module name, the named module or package must be +importable (i.e., be in a distribution or directory on ``sys.path``), and the +``resource_name`` argument is interpreted relative to the named package. (Note +that if a module name is used, then the resource name is relative to the +package immediately containing the named module. Also, you should not use use +a namespace package name, because a namespace package can be spread across +multiple distributions, and is therefore ambiguous as to which distribution +should be searched for the resource.) + +If it is a ``Requirement``, then the requirement is automatically resolved +(searching the current ``Environment`` if necessary) and a matching +distribution is added to the ``WorkingSet`` and ``sys.path`` if one was not +already present. (Unless the ``Requirement`` can't be satisfied, in which +case an exception is raised.) The ``resource_name`` argument is then interpreted +relative to the root of the identified distribution; i.e. its first path +segment will be treated as a peer of the top-level modules or packages in the +distribution. + +Note that resource names must be ``/``-separated paths rooted at the package, +cannot contain relative names like ``".."``, and cannot be absolute. Do *not* use +``os.path`` routines to manipulate resource paths, as they are *not* filesystem +paths. + +``resource_exists(package_or_requirement, resource_name)`` + Does the named resource exist? Return ``True`` or ``False`` accordingly. + +``resource_stream(package_or_requirement, resource_name)`` + Return a readable file-like object for the specified resource; it may be + an actual file, a ``StringIO``, or some similar object. The stream is + in "binary mode", in the sense that whatever bytes are in the resource + will be read as-is. + +``resource_string(package_or_requirement, resource_name)`` + Return the specified resource as ``bytes``. The resource is read in + binary fashion, such that the returned string contains exactly the bytes + that are stored in the resource. + +``resource_isdir(package_or_requirement, resource_name)`` + Is the named resource a directory? Return ``True`` or ``False`` + accordingly. + +``resource_listdir(package_or_requirement, resource_name)`` + List the contents of the named resource directory, just like ``os.listdir`` + except that it works even if the resource is in a zipfile. + +Note that only ``resource_exists()`` and ``resource_isdir()`` are insensitive +as to the resource type. You cannot use ``resource_listdir()`` on a file +resource, and you can't use ``resource_string()`` or ``resource_stream()`` on +directory resources. Using an inappropriate method for the resource type may +result in an exception or undefined behavior, depending on the platform and +distribution format involved. + + +Resource Extraction +------------------- + +``resource_filename(package_or_requirement, resource_name)`` + Sometimes, it is not sufficient to access a resource in string or stream + form, and a true filesystem filename is needed. In such cases, you can + use this method (or module-level function) to obtain a filename for a + resource. If the resource is in an archive distribution (such as a zipped + egg), it will be extracted to a cache directory, and the filename within + the cache will be returned. If the named resource is a directory, then + all resources within that directory (including subdirectories) are also + extracted. If the named resource is a C extension or "eager resource" + (see the ``setuptools`` documentation for details), then all C extensions + and eager resources are extracted at the same time. + + Archived resources are extracted to a cache location that can be managed by + the following two methods: + +``set_extraction_path(path)`` + Set the base path where resources will be extracted to, if needed. + + If you do not call this routine before any extractions take place, the + path defaults to the return value of ``get_default_cache()``. (Which is + based on the ``PYTHON_EGG_CACHE`` environment variable, with various + platform-specific fallbacks. See that routine's documentation for more + details.) + + Resources are extracted to subdirectories of this path based upon + information given by the resource provider. You may set this to a + temporary directory, but then you must call ``cleanup_resources()`` to + delete the extracted files when done. There is no guarantee that + ``cleanup_resources()`` will be able to remove all extracted files. (On + Windows, for example, you can't unlink .pyd or .dll files that are still + in use.) + + Note that you may not change the extraction path for a given resource + manager once resources have been extracted, unless you first call + ``cleanup_resources()``. + +``cleanup_resources(force=False)`` + Delete all extracted resource files and directories, returning a list + of the file and directory names that could not be successfully removed. + This function does not have any concurrency protection, so it should + generally only be called when the extraction path is a temporary + directory exclusive to a single process. This method is not + automatically called; you must call it explicitly or register it as an + ``atexit`` function if you wish to ensure cleanup of a temporary + directory used for extractions. + + +"Provider" Interface +-------------------- + +If you are implementing an ``IResourceProvider`` and/or ``IMetadataProvider`` +for a new distribution archive format, you may need to use the following +``IResourceManager`` methods to coordinate extraction of resources to the +filesystem. If you're not implementing an archive format, however, you have +no need to use these methods. Unlike the other methods listed above, they are +*not* available as top-level functions tied to the global ``ResourceManager``; +you must therefore have an explicit ``ResourceManager`` instance to use them. + +``get_cache_path(archive_name, names=())`` + Return absolute location in cache for ``archive_name`` and ``names`` + + The parent directory of the resulting path will be created if it does + not already exist. ``archive_name`` should be the base filename of the + enclosing egg (which may not be the name of the enclosing zipfile!), + including its ".egg" extension. ``names``, if provided, should be a + sequence of path name parts "under" the egg's extraction location. + + This method should only be called by resource providers that need to + obtain an extraction location, and only for names they intend to + extract, as it tracks the generated names for possible cleanup later. + +``extraction_error()`` + Raise an ``ExtractionError`` describing the active exception as interfering + with the extraction process. You should call this if you encounter any + OS errors extracting the file to the cache path; it will format the + operating system exception for you, and add other information to the + ``ExtractionError`` instance that may be needed by programs that want to + wrap or handle extraction errors themselves. + +``postprocess(tempname, filename)`` + Perform any platform-specific postprocessing of ``tempname``. + Resource providers should call this method ONLY after successfully + extracting a compressed resource. They must NOT call it on resources + that are already in the filesystem. + + ``tempname`` is the current (temporary) name of the file, and ``filename`` + is the name it will be renamed to by the caller after this routine + returns. + + +Metadata API +============ + +The metadata API is used to access metadata resources bundled in a pluggable +distribution. Metadata resources are virtual files or directories containing +information about the distribution, such as might be used by an extensible +application or framework to connect "plugins". Like other kinds of resources, +metadata resource names are ``/``-separated and should not contain ``..`` or +begin with a ``/``. You should not use ``os.path`` routines to manipulate +resource paths. + +The metadata API is provided by objects implementing the ``IMetadataProvider`` +or ``IResourceProvider`` interfaces. ``Distribution`` objects implement this +interface, as do objects returned by the ``get_provider()`` function: + +``get_provider(package_or_requirement)`` + If a package name is supplied, return an ``IResourceProvider`` for the + package. If a ``Requirement`` is supplied, resolve it by returning a + ``Distribution`` from the current working set (searching the current + ``Environment`` if necessary and adding the newly found ``Distribution`` + to the working set). If the named package can't be imported, or the + ``Requirement`` can't be satisfied, an exception is raised. + + NOTE: if you use a package name rather than a ``Requirement``, the object + you get back may not be a pluggable distribution, depending on the method + by which the package was installed. In particular, "development" packages + and "single-version externally-managed" packages do not have any way to + map from a package name to the corresponding project's metadata. Do not + write code that passes a package name to ``get_provider()`` and then tries + to retrieve project metadata from the returned object. It may appear to + work when the named package is in an ``.egg`` file or directory, but + it will fail in other installation scenarios. If you want project + metadata, you need to ask for a *project*, not a package. + + +``IMetadataProvider`` Methods +----------------------------- + +The methods provided by objects (such as ``Distribution`` instances) that +implement the ``IMetadataProvider`` or ``IResourceProvider`` interfaces are: + +``has_metadata(name)`` + Does the named metadata resource exist? + +``metadata_isdir(name)`` + Is the named metadata resource a directory? + +``metadata_listdir(name)`` + List of metadata names in the directory (like ``os.listdir()``) + +``get_metadata(name)`` + Return the named metadata resource as a string. The data is read in binary + mode; i.e., the exact bytes of the resource file are returned. + +``get_metadata_lines(name)`` + Yield named metadata resource as list of non-blank non-comment lines. This + is short for calling ``yield_lines(provider.get_metadata(name))``. See the + section on `yield_lines()`_ below for more information on the syntax it + recognizes. + +``run_script(script_name, namespace)`` + Execute the named script in the supplied namespace dictionary. Raises + ``ResolutionError`` if there is no script by that name in the ``scripts`` + metadata directory. ``namespace`` should be a Python dictionary, usually + a module dictionary if the script is being run as a module. + + +Exceptions +========== + +``pkg_resources`` provides a simple exception hierarchy for problems that may +occur when processing requests to locate and activate packages:: + + ResolutionError + DistributionNotFound + VersionConflict + UnknownExtra + + ExtractionError + +``ResolutionError`` + This class is used as a base class for the other three exceptions, so that + you can catch all of them with a single "except" clause. It is also raised + directly for miscellaneous requirement-resolution problems like trying to + run a script that doesn't exist in the distribution it was requested from. + +``DistributionNotFound`` + A distribution needed to fulfill a requirement could not be found. + +``VersionConflict`` + The requested version of a project conflicts with an already-activated + version of the same project. + +``UnknownExtra`` + One of the "extras" requested was not recognized by the distribution it + was requested from. + +``ExtractionError`` + A problem occurred extracting a resource to the Python Egg cache. The + following attributes are available on instances of this exception: + + manager + The resource manager that raised this exception + + cache_path + The base directory for resource extraction + + original_error + The exception instance that caused extraction to fail + + +Supporting Custom Importers +=========================== + +By default, ``pkg_resources`` supports normal filesystem imports, and +``zipimport`` importers. If you wish to use the ``pkg_resources`` features +with other (PEP 302-compatible) importers or module loaders, you may need to +register various handlers and support functions using these APIs: + +``register_finder(importer_type, distribution_finder)`` + Register ``distribution_finder`` to find distributions in ``sys.path`` items. + ``importer_type`` is the type or class of a PEP 302 "Importer" (``sys.path`` + item handler), and ``distribution_finder`` is a callable that, when passed a + path item, the importer instance, and an ``only`` flag, yields + ``Distribution`` instances found under that path item. (The ``only`` flag, + if true, means the finder should yield only ``Distribution`` objects whose + ``location`` is equal to the path item provided.) + + See the source of the ``pkg_resources.find_on_path`` function for an + example finder function. + +``register_loader_type(loader_type, provider_factory)`` + Register ``provider_factory`` to make ``IResourceProvider`` objects for + ``loader_type``. ``loader_type`` is the type or class of a PEP 302 + ``module.__loader__``, and ``provider_factory`` is a function that, when + passed a module object, returns an `IResourceProvider`_ for that module, + allowing it to be used with the `ResourceManager API`_. + +``register_namespace_handler(importer_type, namespace_handler)`` + Register ``namespace_handler`` to declare namespace packages for the given + ``importer_type``. ``importer_type`` is the type or class of a PEP 302 + "importer" (sys.path item handler), and ``namespace_handler`` is a callable + with a signature like this:: + + def namespace_handler(importer, path_entry, moduleName, module): + # return a path_entry to use for child packages + + Namespace handlers are only called if the relevant importer object has + already agreed that it can handle the relevant path item. The handler + should only return a subpath if the module ``__path__`` does not already + contain an equivalent subpath. Otherwise, it should return None. + + For an example namespace handler, see the source of the + ``pkg_resources.file_ns_handler`` function, which is used for both zipfile + importing and regular importing. + + +IResourceProvider +----------------- + +``IResourceProvider`` is an abstract class that documents what methods are +required of objects returned by a ``provider_factory`` registered with +``register_loader_type()``. ``IResourceProvider`` is a subclass of +``IMetadataProvider``, so objects that implement this interface must also +implement all of the `IMetadataProvider Methods`_ as well as the methods +shown here. The ``manager`` argument to the methods below must be an object +that supports the full `ResourceManager API`_ documented above. + +``get_resource_filename(manager, resource_name)`` + Return a true filesystem path for ``resource_name``, coordinating the + extraction with ``manager``, if the resource must be unpacked to the + filesystem. + +``get_resource_stream(manager, resource_name)`` + Return a readable file-like object for ``resource_name``. + +``get_resource_string(manager, resource_name)`` + Return a string containing the contents of ``resource_name``. + +``has_resource(resource_name)`` + Does the package contain the named resource? + +``resource_isdir(resource_name)`` + Is the named resource a directory? Return a false value if the resource + does not exist or is not a directory. + +``resource_listdir(resource_name)`` + Return a list of the contents of the resource directory, ala + ``os.listdir()``. Requesting the contents of a non-existent directory may + raise an exception. + +Note, by the way, that your provider classes need not (and should not) subclass +``IResourceProvider`` or ``IMetadataProvider``! These classes exist solely +for documentation purposes and do not provide any useful implementation code. +You may instead wish to subclass one of the `built-in resource providers`_. + + +Built-in Resource Providers +--------------------------- + +``pkg_resources`` includes several provider classes that are automatically used +where appropriate. Their inheritance tree looks like this:: + + NullProvider + EggProvider + DefaultProvider + PathMetadata + ZipProvider + EggMetadata + EmptyProvider + FileMetadata + + +``NullProvider`` + This provider class is just an abstract base that provides for common + provider behaviors (such as running scripts), given a definition for just + a few abstract methods. + +``EggProvider`` + This provider class adds in some egg-specific features that are common + to zipped and unzipped eggs. + +``DefaultProvider`` + This provider class is used for unpacked eggs and "plain old Python" + filesystem modules. + +``ZipProvider`` + This provider class is used for all zipped modules, whether they are eggs + or not. + +``EmptyProvider`` + This provider class always returns answers consistent with a provider that + has no metadata or resources. ``Distribution`` objects created without + a ``metadata`` argument use an instance of this provider class instead. + Since all ``EmptyProvider`` instances are equivalent, there is no need + to have more than one instance. ``pkg_resources`` therefore creates a + global instance of this class under the name ``empty_provider``, and you + may use it if you have need of an ``EmptyProvider`` instance. + +``PathMetadata(path, egg_info)`` + Create an ``IResourceProvider`` for a filesystem-based distribution, where + ``path`` is the filesystem location of the importable modules, and ``egg_info`` + is the filesystem location of the distribution's metadata directory. + ``egg_info`` should usually be the ``EGG-INFO`` subdirectory of ``path`` for an + "unpacked egg", and a ``ProjectName.egg-info`` subdirectory of ``path`` for + a "development egg". However, other uses are possible for custom purposes. + +``EggMetadata(zipimporter)`` + Create an ``IResourceProvider`` for a zipfile-based distribution. The + ``zipimporter`` should be a ``zipimport.zipimporter`` instance, and may + represent a "basket" (a zipfile containing multiple ".egg" subdirectories) + a specific egg *within* a basket, or a zipfile egg (where the zipfile + itself is a ".egg"). It can also be a combination, such as a zipfile egg + that also contains other eggs. + +``FileMetadata(path_to_pkg_info)`` + Create an ``IResourceProvider`` that provides exactly one metadata + resource: ``PKG-INFO``. The supplied path should be a distutils PKG-INFO + file. This is basically the same as an ``EmptyProvider``, except that + requests for ``PKG-INFO`` will be answered using the contents of the + designated file. (This provider is used to wrap ``.egg-info`` files + installed by vendor-supplied system packages.) + + +Utility Functions +================= + +In addition to its high-level APIs, ``pkg_resources`` also includes several +generally-useful utility routines. These routines are used to implement the +high-level APIs, but can also be quite useful by themselves. + + +Parsing Utilities +----------------- + +``parse_version(version)`` + Parsed a project's version string as defined by PEP 440. The returned + value will be an object that represents the version. These objects may + be compared to each other and sorted. The sorting algorithm is as defined + by PEP 440 with the addition that any version which is not a valid PEP 440 + version will be considered less than any valid PEP 440 version and the + invalid versions will continue sorting using the original algorithm. + +.. _yield_lines(): + +``yield_lines(strs)`` + Yield non-empty/non-comment lines from a string/unicode or a possibly- + nested sequence thereof. If ``strs`` is an instance of ``basestring``, it + is split into lines, and each non-blank, non-comment line is yielded after + stripping leading and trailing whitespace. (Lines whose first non-blank + character is ``#`` are considered comment lines.) + + If ``strs`` is not an instance of ``basestring``, it is iterated over, and + each item is passed recursively to ``yield_lines()``, so that an arbitrarily + nested sequence of strings, or sequences of sequences of strings can be + flattened out to the lines contained therein. So for example, passing + a file object or a list of strings to ``yield_lines`` will both work. + (Note that between each string in a sequence of strings there is assumed to + be an implicit line break, so lines cannot bridge two strings in a + sequence.) + + This routine is used extensively by ``pkg_resources`` to parse metadata + and file formats of various kinds, and most other ``pkg_resources`` + parsing functions that yield multiple values will use it to break up their + input. However, this routine is idempotent, so calling ``yield_lines()`` + on the output of another call to ``yield_lines()`` is completely harmless. + +``split_sections(strs)`` + Split a string (or possibly-nested iterable thereof), yielding ``(section, + content)`` pairs found using an ``.ini``-like syntax. Each ``section`` is + a whitespace-stripped version of the section name ("``[section]``") + and each ``content`` is a list of stripped lines excluding blank lines and + comment-only lines. If there are any non-blank, non-comment lines before + the first section header, they're yielded in a first ``section`` of + ``None``. + + This routine uses ``yield_lines()`` as its front end, so you can pass in + anything that ``yield_lines()`` accepts, such as an open text file, string, + or sequence of strings. ``ValueError`` is raised if a malformed section + header is found (i.e. a line starting with ``[`` but not ending with + ``]``). + + Note that this simplistic parser assumes that any line whose first nonblank + character is ``[`` is a section heading, so it can't support .ini format + variations that allow ``[`` as the first nonblank character on other lines. + +``safe_name(name)`` + Return a "safe" form of a project's name, suitable for use in a + ``Requirement`` string, as a distribution name, or a PyPI project name. + All non-alphanumeric runs are condensed to single "-" characters, such that + a name like "The $$$ Tree" becomes "The-Tree". Note that if you are + generating a filename from this value you should combine it with a call to + ``to_filename()`` so all dashes ("-") are replaced by underscores ("_"). + See ``to_filename()``. + +``safe_version(version)`` + This will return the normalized form of any PEP 440 version. If the version + string is not PEP 440 compatible, this function behaves similar to + ``safe_name()`` except that spaces in the input become dots, and dots are + allowed to exist in the output. As with ``safe_name()``, if you are + generating a filename from this you should replace any "-" characters in + the output with underscores. + +``safe_extra(extra)`` + Return a "safe" form of an extra's name, suitable for use in a requirement + string or a setup script's ``extras_require`` keyword. This routine is + similar to ``safe_name()`` except that non-alphanumeric runs are replaced + by a single underbar (``_``), and the result is lowercased. + +``to_filename(name_or_version)`` + Escape a name or version string so it can be used in a dash-separated + filename (or ``#egg=name-version`` tag) without ambiguity. You + should only pass in values that were returned by ``safe_name()`` or + ``safe_version()``. + + +Platform Utilities +------------------ + +``get_build_platform()`` + Return this platform's identifier string. For Windows, the return value + is ``"win32"``, and for macOS it is a string of the form + ``"macosx-10.4-ppc"``. All other platforms return the same uname-based + string that the ``distutils.util.get_platform()`` function returns. + This string is the minimum platform version required by distributions built + on the local machine. (Backward compatibility note: setuptools versions + prior to 0.6b1 called this function ``get_platform()``, and the function is + still available under that name for backward compatibility reasons.) + +``get_supported_platform()`` (New in 0.6b1) + This is the similar to ``get_build_platform()``, but is the maximum + platform version that the local machine supports. You will usually want + to use this value as the ``provided`` argument to the + ``compatible_platforms()`` function. + +``compatible_platforms(provided, required)`` + Return true if a distribution built on the ``provided`` platform may be used + on the ``required`` platform. If either platform value is ``None``, it is + considered a wildcard, and the platforms are therefore compatible. + Likewise, if the platform strings are equal, they're also considered + compatible, and ``True`` is returned. Currently, the only non-equal + platform strings that are considered compatible are macOS platform + strings with the same hardware type (e.g. ``ppc``) and major version + (e.g. ``10``) with the ``provided`` platform's minor version being less than + or equal to the ``required`` platform's minor version. + +``get_default_cache()`` + Determine the default cache location for extracting resources from zipped + eggs. This routine returns the ``PYTHON_EGG_CACHE`` environment variable, + if set. Otherwise, on Windows, it returns a "Python-Eggs" subdirectory of + the user's "Application Data" directory. On all other systems, it returns + ``os.path.expanduser("~/.python-eggs")`` if ``PYTHON_EGG_CACHE`` is not + set. + + +PEP 302 Utilities +----------------- + +``get_importer(path_item)`` + A deprecated alias for ``pkgutil.get_importer()`` + + +File/Path Utilities +------------------- + +``ensure_directory(path)`` + Ensure that the parent directory (``os.path.dirname``) of ``path`` actually + exists, using ``os.makedirs()`` if necessary. + +``normalize_path(path)`` + Return a "normalized" version of ``path``, such that two paths represent + the same filesystem location if they have equal ``normalized_path()`` + values. Specifically, this is a shortcut for calling ``os.path.realpath`` + and ``os.path.normcase`` on ``path``. Unfortunately, on certain platforms + (notably Cygwin and macOS) the ``normcase`` function does not accurately + reflect the platform's case-sensitivity, so there is always the possibility + of two apparently-different paths being equal on such platforms. + +History +------- + +0.6c9 + * Fix ``resource_listdir('')`` always returning an empty list for zipped eggs. + +0.6c7 + * Fix package precedence problem where single-version eggs installed in + ``site-packages`` would take precedence over ``.egg`` files (or directories) + installed in ``site-packages``. + +0.6c6 + * Fix extracted C extensions not having executable permissions under Cygwin. + + * Allow ``.egg-link`` files to contain relative paths. + + * Fix cache dir defaults on Windows when multiple environment vars are needed + to construct a path. + +0.6c4 + * Fix "dev" versions being considered newer than release candidates. + +0.6c3 + * Python 2.5 compatibility fixes. + +0.6c2 + * Fix a problem with eggs specified directly on ``PYTHONPATH`` on + case-insensitive filesystems possibly not showing up in the default + working set, due to differing normalizations of ``sys.path`` entries. + +0.6b3 + * Fixed a duplicate path insertion problem on case-insensitive filesystems. + +0.6b1 + * Split ``get_platform()`` into ``get_supported_platform()`` and + ``get_build_platform()`` to work around a Mac versioning problem that caused + the behavior of ``compatible_platforms()`` to be platform specific. + + * Fix entry point parsing when a standalone module name has whitespace + between it and the extras. + +0.6a11 + * Added ``ExtractionError`` and ``ResourceManager.extraction_error()`` so that + cache permission problems get a more user-friendly explanation of the + problem, and so that programs can catch and handle extraction errors if they + need to. + +0.6a10 + * Added the ``extras`` attribute to ``Distribution``, the ``find_plugins()`` + method to ``WorkingSet``, and the ``__add__()`` and ``__iadd__()`` methods + to ``Environment``. + + * ``safe_name()`` now allows dots in project names. + + * There is a new ``to_filename()`` function that escapes project names and + versions for safe use in constructing egg filenames from a Distribution + object's metadata. + + * Added ``Distribution.clone()`` method, and keyword argument support to other + ``Distribution`` constructors. + + * Added the ``DEVELOP_DIST`` precedence, and automatically assign it to + eggs using ``.egg-info`` format. + +0.6a9 + * Don't raise an error when an invalid (unfinished) distribution is found + unless absolutely necessary. Warn about skipping invalid/unfinished eggs + when building an Environment. + + * Added support for ``.egg-info`` files or directories with version/platform + information embedded in the filename, so that system packagers have the + option of including ``PKG-INFO`` files to indicate the presence of a + system-installed egg, without needing to use ``.egg`` directories, zipfiles, + or ``.pth`` manipulation. + + * Changed ``parse_version()`` to remove dashes before pre-release tags, so + that ``0.2-rc1`` is considered an *older* version than ``0.2``, and is equal + to ``0.2rc1``. The idea that a dash *always* meant a post-release version + was highly non-intuitive to setuptools users and Python developers, who + seem to want to use ``-rc`` version numbers a lot. + +0.6a8 + * Fixed a problem with ``WorkingSet.resolve()`` that prevented version + conflicts from being detected at runtime. + + * Improved runtime conflict warning message to identify a line in the user's + program, rather than flagging the ``warn()`` call in ``pkg_resources``. + + * Avoid giving runtime conflict warnings for namespace packages, even if they + were declared by a different package than the one currently being activated. + + * Fix path insertion algorithm for case-insensitive filesystems. + + * Fixed a problem with nested namespace packages (e.g. ``peak.util``) not + being set as an attribute of their parent package. + +0.6a6 + * Activated distributions are now inserted in ``sys.path`` (and the working + set) just before the directory that contains them, instead of at the end. + This allows e.g. eggs in ``site-packages`` to override unmanaged modules in + the same location, and allows eggs found earlier on ``sys.path`` to override + ones found later. + + * When a distribution is activated, it now checks whether any contained + non-namespace modules have already been imported and issues a warning if + a conflicting module has already been imported. + + * Changed dependency processing so that it's breadth-first, allowing a + depender's preferences to override those of a dependee, to prevent conflicts + when a lower version is acceptable to the dependee, but not the depender. + + * Fixed a problem extracting zipped files on Windows, when the egg in question + has had changed contents but still has the same version number. + +0.6a4 + * Fix a bug in ``WorkingSet.resolve()`` that was introduced in 0.6a3. + +0.6a3 + * Added ``safe_extra()`` parsing utility routine, and use it for Requirement, + EntryPoint, and Distribution objects' extras handling. + +0.6a1 + * Enhanced performance of ``require()`` and related operations when all + requirements are already in the working set, and enhanced performance of + directory scanning for distributions. + + * Fixed some problems using ``pkg_resources`` w/PEP 302 loaders other than + ``zipimport``, and the previously-broken "eager resource" support. + + * Fixed ``pkg_resources.resource_exists()`` not working correctly, along with + some other resource API bugs. + + * Many API changes and enhancements: + + * Added ``EntryPoint``, ``get_entry_map``, ``load_entry_point``, and + ``get_entry_info`` APIs for dynamic plugin discovery. + + * ``list_resources`` is now ``resource_listdir`` (and it actually works) + + * Resource API functions like ``resource_string()`` that accepted a package + name and resource name, will now also accept a ``Requirement`` object in + place of the package name (to allow access to non-package data files in + an egg). + + * ``get_provider()`` will now accept a ``Requirement`` instance or a module + name. If it is given a ``Requirement``, it will return a corresponding + ``Distribution`` (by calling ``require()`` if a suitable distribution + isn't already in the working set), rather than returning a metadata and + resource provider for a specific module. (The difference is in how + resource paths are interpreted; supplying a module name means resources + path will be module-relative, rather than relative to the distribution's + root.) + + * ``Distribution`` objects now implement the ``IResourceProvider`` and + ``IMetadataProvider`` interfaces, so you don't need to reference the (no + longer available) ``metadata`` attribute to get at these interfaces. + + * ``Distribution`` and ``Requirement`` both have a ``project_name`` + attribute for the project name they refer to. (Previously these were + ``name`` and ``distname`` attributes.) + + * The ``path`` attribute of ``Distribution`` objects is now ``location``, + because it isn't necessarily a filesystem path (and hasn't been for some + time now). The ``location`` of ``Distribution`` objects in the filesystem + should always be normalized using ``pkg_resources.normalize_path()``; all + of the setuptools' code that generates distributions from the filesystem + (including ``Distribution.from_filename()``) ensure this invariant, but if + you use a more generic API like ``Distribution()`` or + ``Distribution.from_location()`` you should take care that you don't + create a distribution with an un-normalized filesystem path. + + * ``Distribution`` objects now have an ``as_requirement()`` method that + returns a ``Requirement`` for the distribution's project name and version. + + * Distribution objects no longer have an ``installed_on()`` method, and the + ``install_on()`` method is now ``activate()`` (but may go away altogether + soon). The ``depends()`` method has also been renamed to ``requires()``, + and ``InvalidOption`` is now ``UnknownExtra``. + + * ``find_distributions()`` now takes an additional argument called ``only``, + that tells it to only yield distributions whose location is the passed-in + path. (It defaults to False, so that the default behavior is unchanged.) + + * ``AvailableDistributions`` is now called ``Environment``, and the + ``get()``, ``__len__()``, and ``__contains__()`` methods were removed, + because they weren't particularly useful. ``__getitem__()`` no longer + raises ``KeyError``; it just returns an empty list if there are no + distributions for the named project. + + * The ``resolve()`` method of ``Environment`` is now a method of + ``WorkingSet`` instead, and the ``best_match()`` method now uses a working + set instead of a path list as its second argument. + + * There is a new ``pkg_resources.add_activation_listener()`` API that lets + you register a callback for notifications about distributions added to + ``sys.path`` (including the distributions already on it). This is + basically a hook for extensible applications and frameworks to be able to + search for plugin metadata in distributions added at runtime. + +0.5a13 + * Fixed a bug in resource extraction from nested packages in a zipped egg. + +0.5a12 + * Updated extraction/cache mechanism for zipped resources to avoid inter- + process and inter-thread races during extraction. The default cache + location can now be set via the ``PYTHON_EGGS_CACHE`` environment variable, + and the default Windows cache is now a ``Python-Eggs`` subdirectory of the + current user's "Application Data" directory, if the ``PYTHON_EGGS_CACHE`` + variable isn't set. + +0.5a10 + * Fix a problem with ``pkg_resources`` being confused by non-existent eggs on + ``sys.path`` (e.g. if a user deletes an egg without removing it from the + ``easy-install.pth`` file). + + * Fix a problem with "basket" support in ``pkg_resources``, where egg-finding + never actually went inside ``.egg`` files. + + * Made ``pkg_resources`` import the module you request resources from, if it's + not already imported. + +0.5a4 + * ``pkg_resources.AvailableDistributions.resolve()`` and related methods now + accept an ``installer`` argument: a callable taking one argument, a + ``Requirement`` instance. The callable must return a ``Distribution`` + object, or ``None`` if no distribution is found. This feature is used by + EasyInstall to resolve dependencies by recursively invoking itself. + +0.4a4 + * Fix problems with ``resource_listdir()``, ``resource_isdir()`` and resource + directory extraction for zipped eggs. + +0.4a3 + * Fixed scripts not being able to see a ``__file__`` variable in ``__main__`` + + * Fixed a problem with ``resource_isdir()`` implementation that was introduced + in 0.4a2. + +0.4a1 + * Fixed a bug in requirements processing for exact versions (i.e. ``==`` and + ``!=``) when only one condition was included. + + * Added ``safe_name()`` and ``safe_version()`` APIs to clean up handling of + arbitrary distribution names and versions found on PyPI. + +0.3a4 + * ``pkg_resources`` now supports resource directories, not just the resources + in them. In particular, there are ``resource_listdir()`` and + ``resource_isdir()`` APIs. + + * ``pkg_resources`` now supports "egg baskets" -- .egg zipfiles which contain + multiple distributions in subdirectories whose names end with ``.egg``. + Having such a "basket" in a directory on ``sys.path`` is equivalent to + having the individual eggs in that directory, but the contained eggs can + be individually added (or not) to ``sys.path``. Currently, however, there + is no automated way to create baskets. + + * Namespace package manipulation is now protected by the Python import lock. + +0.3a1 + * Initial release. diff --git a/docs/python 2 sunset.rst b/docs/python 2 sunset.rst new file mode 100644 index 00000000..225d6551 --- /dev/null +++ b/docs/python 2 sunset.rst @@ -0,0 +1,69 @@ +:orphan: + +Python 2 Sunset +=============== + +Since January 2020 and the release of Setuptools 45, Python 2 is no longer +supported by the most current release (`discussion +<https://github.com/pypa/setuptools/issues/1458>`_). Setuptools as a project +continues to support Python 2 with bugfixes and important features on +Setuptools 44.x. + +By design, most users will be unaffected by this change. That's because +Setuptools 45 declares its supported Python versions to exclude Python 2.7, +and installers such as pip 9 or later will honor this declaration and prevent +installation of Setuptools 45 or later in Python 2 environments. + +Users that do import any portion of Setuptools 45 or later on Python 2 are +directed to this documentation to provide guidance on how to work around the +issues. + +Workarounds +----------- + +The best recommendation is to avoid Python 2 and move to Python 3 where +possible. This project acknowledges that not all environments can drop Python +2 support, so provides other options. + +In less common scenarios, later versions of Setuptools can be installed on +unsupported Python versions. In these environments, the installer is advised +to first install ``setuptools<45`` to "pin Setuptools" to a compatible +version. + +- When using older versions of pip (before 9.0), the ``Requires-Python`` + directive is not honored and invalid versions can be installed. Users are + advised first to upgrade pip and retry or to pin Setuptools. Use ``pip + --version`` to determine the version of pip. +- When using ``easy_install``, ``Requires-Python`` is not honored and later + versions can be installed. In this case, users are advised to pin + Setuptools. This applies to ``setup.py install`` invocations as well, as + they use Setuptools under the hood. + +It's still not working +---------------------- + +If after trying the above steps, the Python environment still has incompatible +versions of Setuptools installed, here are some things to try. + +1. Uninstall and reinstall Setuptools. Run ``pip uninstall -y setuptools`` for + the relevant environment. Repeat until there is no Setuptools installed. + Then ``pip install setuptools``. +2. If possible, attempt to replicate the problem in a second environment + (virtual machine, friend's computer, etc). If the issue is isolated to just + one unique environment, first determine what is different about those + environments (or reinstall/reset the failing one to defaults). +3. End users who are not themselves the maintainers for the package they are + trying to install should contact the support channels for the relevant + application. Please be considerate of those projects by searching for + existing issues and following the latest guidance before reaching out for + support. When filing an issue, be sure to give as much detail as possible + to help the maintainers understand what factors led to the issue after + following their recommended guidance. +4. Reach out to your local support groups. There's a good chance someone + nearby has the expertise and willingness to help. +5. If all else fails, `file this template + <https://github.com/pypa/setuptools/issues/new?assignees=&labels=Python+2&template=setuptools-warns-about-python-2-incompatibility.md&title=Incompatible+install+in+(summarize+your+environment)>`_ + with Setuptools. Please complete the whole template, providing as much + detail about what factors led to the issue. Setuptools maintainers will + summarily close tickets filed without any meaningful detail or engagement + with the issue. diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst new file mode 100644 index 00000000..ade147ad --- /dev/null +++ b/docs/references/keywords.rst @@ -0,0 +1,498 @@ +======== +Keywords +======== + +The following are keywords ``setuptools.setup()`` accepts. +They allow configuring the build process for a Python distribution or adding +metadata via a ``setup.py`` script placed at the root of your project. +All of them are optional; you do not have to supply them unless you need the +associated ``setuptools`` feature. + +Metadata and configuration supplied via ``setup()`` is complementary to (and +may be overwritten by) the information present in ``setup.cfg`` and ``pyproject.toml``. +Some important metadata, such as ``name`` and ``version``, may assume +a default *degenerate* value if not specified. + +Users are strongly encouraged to use a declarative config either via +:doc:`setup.cfg </userguide/declarative_config>` or :doc:`pyproject.toml +</userguide/pyproject_config>` and only rely on ``setup.py`` if they need to +tap into special behaviour that requires scripting (such as building C +extensions). + +.. note:: + When using declarative configs via ``pyproject.toml`` + with ``setuptools<64.0.0``, users can still keep a very simple ``setup.py`` + just to ensure editable installs are supported, for example:: + + from setuptools import setup + + setup() + + Versions of ``setuptools`` ``>=64.0.0`` do not require this extra minimal + ``setup.py`` file. + +.. _keyword/name: + +``name`` + A string specifying the name of the package. + +.. _keyword/version: + +``version`` + A string specifying the version number of the package. + +.. _keyword/description: + +``description`` + A string describing the package in a single line. + +.. _keyword/long_description: + +``long_description`` + A string providing a longer description of the package. + +.. _keyword/long_description_content_type: + +``long_description_content_type`` + A string specifying the content type is used for the ``long_description`` + (e.g. ``text/markdown``) + +.. _keyword/author: + +``author`` + A string specifying the author of the package. + +.. _keyword/author_email: + +``author_email`` + A string specifying the email address of the package author. + +.. _keyword/maintainer: + +``maintainer`` + A string specifying the name of the current maintainer, if different from + the author. Note that if the maintainer is provided, setuptools will use it + as the author in ``PKG-INFO``. + +.. _keyword/maintainer_email: + +``maintainer_email`` + A string specifying the email address of the current maintainer, if + different from the author. + +.. _keyword/url: + +``url`` + A string specifying the URL for the package homepage. + +.. _keyword/download_url: + +``download_url`` + A string specifying the URL to download the package. + +.. _keyword/packages: + +``packages`` + A list of strings specifying the packages that setuptools will manipulate. + +.. _keyword/py_modules: + +``py_modules`` + A list of strings specifying the modules that setuptools will manipulate. + +.. _keyword/scripts: + +``scripts`` + A list of strings specifying the standalone script files to be built and + installed. + +.. _keyword/ext_package: + +``ext_package`` + A string specifying the base package name for the extensions provided by + this package. + +.. _keyword/ext_modules: + +``ext_modules`` + A list of instances of ``setuptools.Extension`` providing the list of + Python extensions to be built. + +.. _keyword/classifiers: + +``classifiers`` + A list of strings describing the categories for the package. + +.. _keyword/distclass: + +``distclass`` + A subclass of ``Distribution`` to use. + +.. _keyword/script_name: + +``script_name`` + A string specifying the name of the setup.py script -- defaults to + ``sys.argv[0]`` + +.. _keyword/script_args: + +``script_args`` + A list of strings defining the arguments to supply to the setup script. + +.. _keyword/options: + +``options`` + A dictionary providing the default options for the setup script. + +.. _keyword/license: + +``license`` + A string specifying the license of the package. + +.. _keyword/license_file: + +``license_file`` + .. warning:: + ``license_file`` is deprecated. Use ``license_files`` instead. + +.. _keyword/license_files: + +``license_files`` + A list of glob patterns for license related files that should be included. + If neither ``license_file`` nor ``license_files`` is specified, this option + defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``. + +.. _keyword/keywords: + +``keywords`` + A list of strings or a comma-separated string providing descriptive + meta-data. See: :ref:`Core Metadata Specifications<core-metadata-keywords>`. + +.. _keyword/platforms: + +``platforms`` + A list of strings or comma-separated string. + +.. _keyword/cmdclass: + +``cmdclass`` + A dictionary providing a mapping of command names to ``Command`` + subclasses. + +.. _keyword/data_files: + +``data_files`` + .. warning:: + ``data_files`` is deprecated. It does not work with wheels, so it + should be avoided. + + A list of strings specifying the data files to install. + +.. _keyword/package_dir: + +``package_dir`` + A dictionary that maps package names (as they will be + imported by the end-users) into directory paths (that actually exist in the + project's source tree). This configuration has two main purposes: + + 1. To effectively "rename" paths when building your package. + For example, ``package_dir={"mypkg": "dir1/dir2/code_for_mypkg"}`` + will instruct setuptools to copy the ``dir1/dir2/code_for_mypkg/...`` files + as ``mypkg/...`` when building the final :term:`wheel distribution <Wheel>`. + + .. attention:: + While it is *possible* to specify arbitrary mappings, developers are + **STRONGLY ADVISED AGAINST** that. They should try as much as possible + to keep the directory names and hierarchy identical to the way they will + appear in the final wheel, only deviating when absolutely necessary. + + 2. To indicate that the relevant code is entirely contained inside + a specific directory (instead of directly placed under the project's root). + In this case, a special key is required (the empty string, ``""``), + for example: ``package_dir={"": "<name of the container directory>"}``. + All the directories inside the container directory will be copied + directly into the final :term:`wheel distribution <Wheel>`, but the + container directory itself will not. + + This practice is very common in the community to help separate the + package implementation from auxiliary files (e.g. CI configuration files), + and is referred to as :ref:`src-layout`, because the container + directory is commonly named ``src``. + + All paths in ``package_dir`` must be relative to the project root directory + and use a forward slash (``/``) as path separator regardless of the + operating system. + + .. tip:: + When using :doc:`package discovery </userguide/package_discovery>` + together with :doc:`setup.cfg </userguide/declarative_config>` or + :doc:`pyproject.toml </userguide/pyproject_config>`, it is very likely + that you don't need to specify a value for ``package_dir``. Please have + a look at the definitions of :ref:`src-layout` and :ref:`flat-layout` to + learn common practices on how to design a project's directory structure + and minimise the amount of configuration that is needed. + +.. _keyword/requires: + +``requires`` + .. warning:: + ``requires`` is superseded by ``install_requires`` and should not be used + anymore. + +.. _keyword/obsoletes: + +``obsoletes`` + .. warning:: + ``obsoletes`` is currently ignored by ``pip``. + + List of strings describing packages which this package renders obsolete, + meaning that the two projects should not be installed at the same time. + + Version declarations can be supplied. Version numbers must be in the format + specified in Version specifiers (e.g. ``foo (<3.0)``). + + This field may be followed by an environment marker after a semicolon (e.g. + ``foo; os_name == "posix"``) + + The most common use of this field will be in case a project name changes, + e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install + Torqued Python, the Gorgon distribution should be removed. + +.. _keyword/provides: + +``provides`` + .. warning:: + ``provides`` is currently ignored by ``pip``. + + List of strings describing package- and virtual package names contained + within this package. + + A package may provide additional names, e.g. to indicate that multiple + projects have been bundled together. For instance, source distributions of + the ZODB project have historically included the transaction project, which + is now available as a separate distribution. Installing such a source + distribution satisfies requirements for both ZODB and transaction. + + A package may also provide a “virtual” project name, which does not + correspond to any separately-distributed project: such a name might be used + to indicate an abstract capability which could be supplied by one of + multiple projects. E.g., multiple projects might supply RDBMS bindings for + use by a given ORM: each project might declare that it provides + ORM-bindings, allowing other projects to depend only on having at most one + of them installed. + + A version declaration may be supplied and must follow the rules described in + Version specifiers. The distribution’s version number will be implied if + none is specified (e.g. ``foo (<3.0)``). + + Each package may be followed by an environment marker after a semicolon + (e.g. ``foo; os_name == "posix"``). + +.. _keyword/include_package_data: + +``include_package_data`` + If set to ``True``, this tells ``setuptools`` to automatically include any + data files it finds inside your package directories that are specified by + your ``MANIFEST.in`` file. For more information, see the section on + :ref:`Including Data Files`. + +.. _keyword/exclude_package_data: + +``exclude_package_data`` + A dictionary mapping package names to lists of glob patterns that should + be *excluded* from your package directories. You can use this to trim back + any excess files included by ``include_package_data``. For a complete + description and examples, see the section on :ref:`Including Data Files`. + +.. _keyword/package_data: + +``package_data`` + A dictionary mapping package names to lists of glob patterns. For a + complete description and examples, see the section on :ref:`Including Data + Files`. You do not need to use this option if you are using + ``include_package_data``, unless you need to add e.g. files that are + generated by your setup script and build process. (And are therefore not + in source control or are files that you don't want to include in your + source distribution.) + +.. _keyword/zip_safe: + +``zip_safe`` + A boolean (True or False) flag specifying whether the project can be + safely installed and run from a zip file. If this argument is not + supplied, the ``bdist_egg`` command will have to analyze all of your + project's contents for possible problems each time it builds an egg. + +.. _keyword/install_requires: + +``install_requires`` + A string or list of strings specifying what other distributions need to + be installed when this one is. See the section on :ref:`Declaring + Dependencies` for details and examples of the format of this argument. + +.. _keyword/entry_points: + +``entry_points`` + A dictionary mapping entry point group names to strings or lists of strings + defining the entry points. Entry points are used to support dynamic + discovery of services or plugins provided by a project. See :ref:`Dynamic + Discovery of Services and Plugins` for details and examples of the format + of this argument. In addition, this keyword is used to support + :ref:`Automatic Script Creation <entry_points>`. + +.. _keyword/extras_require: + +``extras_require`` + A dictionary mapping names of "extras" (optional features of your project) + to strings or lists of strings specifying what other distributions must be + installed to support those features. See the section on :ref:`Declaring + Dependencies` for details and examples of the format of this argument. + +.. _keyword/python_requires: + +``python_requires`` + A string corresponding to a version specifier (as defined in PEP 440) for + the Python version, used to specify the Requires-Python defined in PEP 345. + +.. _keyword/setup_requires: + +``setup_requires`` + .. warning:: + Using ``setup_requires`` is discouraged in favor of :pep:`518`. + + A string or list of strings specifying what other distributions need to + be present in order for the *setup script* to run. ``setuptools`` will + attempt to obtain these before processing the + rest of the setup script or commands. This argument is needed if you + are using distutils extensions as part of your build process; for + example, extensions that process setup() arguments and turn them into + EGG-INFO metadata files. + + (Note: projects listed in ``setup_requires`` will NOT be automatically + installed on the system where the setup script is being run. They are + simply downloaded to the ./.eggs directory if they're not locally available + already. If you want them to be installed, as well as being available + when the setup script is run, you should add them to ``install_requires`` + **and** ``setup_requires``.) + +.. _keyword/dependency_links: + +``dependency_links`` + .. warning:: + ``dependency_links`` is deprecated. It is not supported anymore by pip. + + A list of strings naming URLs to be searched when satisfying dependencies. + These links will be used if needed to install packages specified by + ``setup_requires`` or ``tests_require``. They will also be written into + the egg's metadata for use during install by tools that support them. + +.. _keyword/namespace_packages: + +``namespace_packages`` + .. warning:: + ``namespace_packages`` is deprecated in favor of native/implicit + namespaces (:pep:`420`). Check :doc:`the Python Packaging User Guide + <PyPUG:guides/packaging-namespace-packages>` for more information. + + A list of strings naming the project's "namespace packages". A namespace + package is a package that may be split across multiple project + distributions. For example, Zope 3's ``zope`` package is a namespace + package, because subpackages like ``zope.interface`` and ``zope.publisher`` + may be distributed separately. The egg runtime system can automatically + merge such subpackages into a single parent package at runtime, as long + as you declare them in each project that contains any subpackages of the + namespace package, and as long as the namespace package's ``__init__.py`` + does not contain any code other than a namespace declaration. See the + section on :ref:`Namespace Packages` for more information. + +.. _keyword/test_suite: + +``test_suite`` + A string naming a ``unittest.TestCase`` subclass (or a package or module + containing one or more of them, or a method of such a subclass), or naming + a function that can be called with no arguments and returns a + ``unittest.TestSuite``. If the named suite is a module, and the module + has an ``additional_tests()`` function, it is called and the results are + added to the tests to be run. If the named suite is a package, any + submodules and subpackages are recursively added to the overall test suite. + + Specifying this argument enables use of the :ref:`test <test>` command to run the + specified test suite, e.g. via ``setup.py test``. See the section on the + :ref:`test <test>` command below for more details. + + .. warning:: + .. deprecated:: 41.5.0 + The test command will be removed in a future version of ``setuptools``, + alongside any test configuration parameter. + +.. _keyword/tests_require: + +``tests_require`` + If your project's tests need one or more additional packages besides those + needed to install it, you can use this option to specify them. It should + be a string or list of strings specifying what other distributions need to + be present for the package's tests to run. When you run the ``test`` + command, ``setuptools`` will attempt to obtain these. + Note that these required projects will *not* be installed on + the system where the tests are run, but only downloaded to the project's setup + directory if they're not already installed locally. + + .. warning:: + .. deprecated:: 41.5.0 + The test command will be removed in a future version of ``setuptools``, + alongside any test configuration parameter. + +.. _test_loader: + +.. _keyword/test_loader: + +``test_loader`` + If you would like to use a different way of finding tests to run than what + setuptools normally uses, you can specify a module name and class name in + this argument. The named class must be instantiable with no arguments, and + its instances must support the ``loadTestsFromNames()`` method as defined + in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will + pass only one test "name" in the ``names`` argument: the value supplied for + the ``test_suite`` argument. The loader you specify may interpret this + string in any way it likes, as there are no restrictions on what may be + contained in a ``test_suite`` string. + + The module name and class name must be separated by a ``:``. The default + value of this argument is ``"setuptools.command.test:ScanningLoader"``. If + you want to use the default ``unittest`` behavior, you can specify + ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This + will prevent automatic scanning of submodules and subpackages. + + The module and class you specify here may be contained in another package, + as long as you use the ``tests_require`` option to ensure that the package + containing the loader class is available when the ``test`` command is run. + + .. warning:: + .. deprecated:: 41.5.0 + The test command will be removed in a future version of ``setuptools``, + alongside any test configuration parameter. + +.. _keyword/eager_resources: + +``eager_resources`` + A list of strings naming resources that should be extracted together, if + any of them is needed, or if any C extensions included in the project are + imported. This argument is only useful if the project will be installed as + a zipfile, and there is a need to have all of the listed resources be + extracted to the filesystem *as a unit*. Resources listed here + should be '/'-separated paths, relative to the source root, so to list a + resource ``foo.png`` in package ``bar.baz``, you would include the string + ``bar/baz/foo.png`` in this argument. + + If you only need to obtain resources one at a time, or you don't have any C + extensions that access other files in the project (such as data files or + shared libraries), you probably do NOT need this argument and shouldn't + mess with it. For more details on how this argument works, see the section + below on :ref:`Automatic Resource Extraction`. + +.. _keyword/project_urls: + +``project_urls`` + An arbitrary map of URL names to hyperlinks, allowing more extensible + documentation of where various resources can be found than the simple + ``url`` and ``download_url`` options provide. diff --git a/docs/roadmap.rst b/docs/roadmap.rst new file mode 100644 index 00000000..147288f3 --- /dev/null +++ b/docs/roadmap.rst @@ -0,0 +1,7 @@ +======= +Roadmap +======= + +Setuptools maintains a series of `milestones +<https://github.com/pypa/setuptools/milestones>`_ to track +a roadmap of large-scale goals. diff --git a/docs/setuptools.rst b/docs/setuptools.rst new file mode 100644 index 00000000..53170589 --- /dev/null +++ b/docs/setuptools.rst @@ -0,0 +1,227 @@ +================================================== +Building and Distributing Packages with Setuptools +================================================== + +``Setuptools`` is a collection of enhancements to the Python ``distutils`` +that allow developers to more easily build and +distribute Python packages, especially ones that have dependencies on other +packages. + +Packages built and distributed using ``setuptools`` look to the user like +ordinary Python packages based on the ``distutils``. + +Feature Highlights: + +* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ - + a single-file importable distribution format + +* Enhanced support for accessing data files hosted in zipped packages. + +* Automatically include all packages in your source tree, without listing them + individually in setup.py + +* Automatically include all relevant files in your source distributions, + without needing to create a |MANIFEST.in|_ file, and without having to force + regeneration of the ``MANIFEST`` file when your source tree changes + [#manifest]_. + +* Automatically generate wrapper scripts or Windows (console and GUI) .exe + files for any number of "main" functions in your project. (Note: this is not + a py2exe replacement; the .exe files rely on the local Python installation.) + +* Transparent Cython support, so that your setup.py can list ``.pyx`` files and + still work even when the end-user doesn't have Cython installed (as long as + you include the Cython-generated C in your source distribution) + +* Command aliases - create project-specific, per-user, or site-wide shortcut + names for commonly used commands and options + +* Deploy your project in "development mode", such that it's available on + ``sys.path``, yet can still be edited directly from its source checkout. + +* Easily extend the distutils with new commands or ``setup()`` arguments, and + distribute/reuse your extensions for multiple projects, without copying code. + +* Create extensible applications and frameworks that automatically discover + extensions, using simple "entry points" declared in a project's setup script. + +* Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards + compatible to the existing ``find_packages()`` for Python >= 3.3. + +----------------- +Developer's Guide +----------------- + +The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +TRANSITIONAL NOTE +~~~~~~~~~~~~~~~~~ + +Setuptools automatically calls ``declare_namespace()`` for you at runtime, +but future versions may *not*. This is because the automatic declaration +feature has some negative side effects, such as needing to import all namespace +packages during the initialization of the ``pkg_resources`` runtime, and also +the need for ``pkg_resources`` to be explicitly imported before any namespace +packages work at all. In some future releases, you'll be responsible +for including your own declaration lines, and the automatic declaration feature +will be dropped to get rid of the negative side effects. + +During the remainder of the current development cycle, therefore, setuptools +will warn you about missing ``declare_namespace()`` calls in your +``__init__.py`` files, and you should correct these as soon as possible +before the compatibility support is removed. +Namespace packages without declaration lines will not work +correctly once a user has upgraded to a later version, so it's important that +you make this change now in order to avoid having your code break in the field. +Our apologies for the inconvenience, and thank you for your patience. + + + + + + + + + + + + + + + + + +setup.cfg-only projects +======================= + +.. versionadded:: 40.9.0 + +If ``setup.py`` is missing from the project directory when a :pep:`517` +build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing +only a ``setuptools.setup()`` call. + +.. note:: + + :pep:`517` doesn't support editable installs so this is currently + incompatible with ``pip install -e .``. + +This means that you can have a Python project with all build configuration +specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely +on** your project always being built by a :pep:`517`/:pep:`518` compatible +frontend. + +To use this feature: + +* Specify build requirements and :pep:`517` build backend in + ``pyproject.toml``. + For example: + + .. code-block:: toml + + [build-system] + requires = [ + "setuptools >= 40.9.0", + ] + build-backend = "setuptools.build_meta" + +* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``. + + .. warning:: + + As :pep:`517` is new, support is not universal, and frontends that + do support it may still have bugs. For compatibility, you may want to + put a ``setup.py`` file containing only a ``setuptools.setup()`` + invocation. + + +Configuration API +================= + +Some automation tools may wish to access data from a configuration file. + +``Setuptools`` exposes a ``read_configuration()`` function for +parsing ``metadata`` and ``options`` sections into a dictionary. + + +.. code-block:: python + + from setuptools.config import read_configuration + + conf_dict = read_configuration("/home/user/dev/package/setup.cfg") + + +By default, ``read_configuration()`` will read only the file provided +in the first argument. To include values from other configuration files +which could be in various places, set the ``find_others`` keyword argument +to ``True``. + +If you have only a configuration file but not the whole package, you can still +try to get data out of it with the help of the ``ignore_option_errors`` keyword +argument. When it is set to ``True``, all options with errors possibly produced +by directives, such as ``attr:`` and others, will be silently ignored. +As a consequence, the resulting dictionary will include no such options. + + + + + + + + + + + +Forum and Bug Tracker +===================== + +Please use `GitHub Discussions`_ for questions and discussion about +setuptools, and the `setuptools bug tracker`_ ONLY for issues you have +confirmed via the forum are actual bugs, and which you have reduced to a minimal +set of steps to reproduce. + +.. _GitHub Discussions: https://github.com/pypa/setuptools/discussions +.. _setuptools bug tracker: https://github.com/pypa/setuptools/ + + +---- + + +.. [#manifest] The default behaviour for ``setuptools`` will work well for pure + Python packages, or packages with simple C extensions (that don't require + any special C header). See :ref:`Controlling files in the distribution` and + :doc:`userguide/datafiles` for more information about complex scenarios, if + you want to include other types of files. + + +.. |MANIFEST.in| replace:: ``MANIFEST.in`` +.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/ diff --git a/docs/userguide/datafiles.rst b/docs/userguide/datafiles.rst new file mode 100644 index 00000000..44ff7425 --- /dev/null +++ b/docs/userguide/datafiles.rst @@ -0,0 +1,555 @@ +==================== +Data Files Support +==================== + +Old packaging installation methods in the Python ecosystem +have traditionally allowed installation of "data files", which +are placed in a platform-specific location. However, the most common use case +for data files distributed with a package is for use *by* the package, usually +by including the data files **inside the package directory**. + +Setuptools focuses on this most common type of data files and offers three ways +of specifying which files should be included in your packages, as described in +the following sections. + +include_package_data +==================== + +First, you can simply use the ``include_package_data`` keyword. +For example, if the package tree looks like this:: + + project_root_directory + ├── setup.py # and/or setup.cfg, pyproject.toml + └── src + └── mypkg + ├── __init__.py + ├── data1.rst + ├── data2.rst + ├── data1.txt + └── data2.txt + +and you supply this configuration: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + # ... + packages = find: + package_dir = + = src + include_package_data = True + + [options.packages.find] + where = src + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup, find_packages + setup( + # ..., + packages=find_packages(where="src"), + package_dir={"": "src"}, + include_package_data=True + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools] + # ... + # By default, include-package-data is true in pyproject.toml, so you do + # NOT have to specify this line. + include-package-data = true + + [tool.setuptools.packages.find] + where = ["src"] + +then all the ``.txt`` and ``.rst`` files will be automatically installed with +your package, provided: + +1. These files are included via the |MANIFEST.in|_ file, like so:: + + include src/mypkg/*.txt + include src/mypkg/*.rst + +2. OR, they are being tracked by a revision control system such as Git, Mercurial + or SVN, and you have configured an appropriate plugin such as + :pypi:`setuptools-scm` or :pypi:`setuptools-svn`. + (See the section below on :ref:`Adding Support for Revision + Control Systems` for information on how to write such plugins.) + +package_data +============ + +By default, ``include_package_data`` considers **all** non ``.py`` files found inside +the package directory (``src/mypkg`` in this case) as data files, and includes those that +satisfy (at least) one of the above two conditions into the source distribution, and +consequently in the installation of your package. +If you want finer-grained control over what files are included, then you can also use +the ``package_data`` keyword. +For example, if the package tree looks like this:: + + project_root_directory + ├── setup.py # and/or setup.cfg, pyproject.toml + └── src + └── mypkg + ├── __init__.py + ├── data1.rst + ├── data2.rst + ├── data1.txt + └── data2.txt + +then you can use the following configuration to capture the ``.txt`` and ``.rst`` files as +data files: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + # ... + packages = find: + package_dir = + = src + + [options.packages.find] + where = src + + [options.package_data] + mypkg = + *.txt + *.rst + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup, find_packages + setup( + # ..., + packages=find_packages(where="src"), + package_dir={"": "src"}, + package_data={"mypkg": ["*.txt", "*.rst"]} + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] + + [tool.setuptools.package-data] + mypkg = ["*.txt", "*.rst"] + +The ``package_data`` argument is a dictionary that maps from package names to +lists of glob patterns. Note that the data files specified using the ``package_data`` +option neither require to be included within a |MANIFEST.in|_ file, nor +require to be added by a revision control system plugin. + +.. note:: + If your glob patterns use paths, you *must* use a forward slash (``/``) as + the path separator, even if you are on Windows. Setuptools automatically + converts slashes to appropriate platform-specific separators at build time. + +.. note:: + Glob patterns do not automatically match dotfiles (directory or file names + starting with a dot (``.``)). To include such files, you must explicitly start + the pattern with a dot, e.g. ``.*`` to match ``.gitignore``. + +If you have multiple top-level packages and a common pattern of data files for all these +packages, for example:: + + project_root_directory + ├── setup.py # and/or setup.cfg, pyproject.toml + └── src + ├── mypkg1 + │ ├── data1.rst + │ ├── data1.txt + │ └── __init__.py + └── mypkg2 + ├── data2.txt + └── __init__.py + +Here, both packages ``mypkg1`` and ``mypkg2`` share a common pattern of having ``.txt`` +data files. However, only ``mypkg1`` has ``.rst`` data files. In such a case, if you want to +use the ``package_data`` option, the following configuration will work: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + packages = find: + package_dir = + = src + + [options.packages.find] + where = src + + [options.package_data] + * = + *.txt + mypkg1 = + data1.rst + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup, find_packages + setup( + # ..., + packages=find_packages(where="src"), + package_dir={"": "src"}, + package_data={"": ["*.txt"], "mypkg1": ["data1.rst"]}, + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] + + [tool.setuptools.package-data] + "*" = ["*.txt"] + mypkg1 = ["data1.rst"] + +Notice that if you list patterns in ``package_data`` under the empty string ``""`` in +``setup.py``, and the asterisk ``*`` in ``setup.cfg`` and ``pyproject.toml``, these +patterns are used to find files in every package. For example, we use ``""`` or ``*`` +to indicate that the ``.txt`` files from all packages should be captured as data files. +Also note how we can continue to specify patterns for individual packages, i.e. +we specify that ``data1.rst`` from ``mypkg1`` alone should be captured as well. + +.. note:: + When building an ``sdist``, the datafiles are also drawn from the + ``package_name.egg-info/SOURCES.txt`` file, so make sure that this is removed if + the ``setup.py`` ``package_data`` list is updated before calling ``setup.py``. + +.. note:: + If using the ``include_package_data`` argument, files specified by + ``package_data`` will *not* be automatically added to the manifest unless + they are listed in the |MANIFEST.in|_ file or by a plugin like + :pypi:`setuptools-scm` or :pypi:`setuptools-svn`. + +.. https://docs.python.org/3/distutils/setupscript.html#installing-package-data + +exclude_package_data +==================== + +Sometimes, the ``include_package_data`` or ``package_data`` options alone +aren't sufficient to precisely define what files you want included. For example, +consider a scenario where you have ``include_package_data=True``, and you are using +a revision control system with an appropriate plugin. +Sometimes developers add directory-specific marker files (such as ``.gitignore``, +``.gitkeep``, ``.gitattributes``, or ``.hgignore``), these files are probably being +tracked by the revision control system, and therefore by default they will be +included when the package is installed. + +Supposing you want to prevent these files from being included in the +installation (they are not relevant to Python or the package), then you could +use the ``exclude_package_data`` option: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + # ... + packages = find: + package_dir = + = src + include_package_data = True + + [options.packages.find] + where = src + + [options.exclude_package_data] + mypkg = + .gitattributes + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup, find_packages + setup( + # ..., + packages=find_packages(where="src"), + package_dir={"": "src"}, + include_package_data=True, + exclude_package_data={"mypkg": [".gitattributes"]}, + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] + + [tool.setuptools.exclude-package-data] + mypkg = [".gitattributes"] + +The ``exclude_package_data`` option is a dictionary mapping package names to +lists of wildcard patterns, just like the ``package_data`` option. And, just +as with that option, you can use the empty string key ``""`` in ``setup.py`` and the +asterisk ``*`` in ``setup.cfg`` and ``pyproject.toml`` to match all top-level packages. + +Any files that match these patterns will be *excluded* from installation, +even if they were listed in ``package_data`` or were included as a result of using +``include_package_data``. + +Subdirectory for Data Files +=========================== + +A common pattern is where some (or all) of the data files are placed under +a separate subdirectory. For example:: + + project_root_directory + ├── setup.py # and/or setup.cfg, pyproject.toml + └── src + └── mypkg + ├── data + │ ├── data1.rst + │ └── data2.rst + ├── __init__.py + ├── data1.txt + └── data2.txt + +Here, the ``.rst`` files are placed under a ``data`` subdirectory inside ``mypkg``, +while the ``.txt`` files are directly under ``mypkg``. + +In this case, the recommended approach is to treat ``data`` as a namespace package +(refer :pep:`420`). With ``package_data``, +the configuration might look like this: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + # ... + packages = find_namespace: + package_dir = + = src + + [options.packages.find] + where = src + + [options.package_data] + mypkg = + *.txt + mypkg.data = + *.rst + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup, find_namespace_packages + setup( + # ..., + packages=find_namespace_packages(where="src"), + package_dir={"": "src"}, + package_data={ + "mypkg": ["*.txt"], + "mypkg.data": ["*.rst"], + } + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools.packages.find] + # scanning for namespace packages is true by default in pyproject.toml, so + # you do NOT need to include the following line. + namespaces = true + where = ["src"] + + [tool.setuptools.package-data] + mypkg = ["*.txt"] + "mypkg.data" = ["*.rst"] + +In other words, we allow Setuptools to scan for namespace packages in the ``src`` directory, +which enables the ``data`` directory to be identified, and then, we separately specify data +files for the root package ``mypkg``, and the namespace package ``data`` under the package +``mypkg``. + +With ``include_package_data`` the configuration is simpler: you simply need to enable +scanning of namespace packages in the ``src`` directory and the rest is handled by Setuptools. + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + packages = find_namespace: + package_dir = + = src + include_package_data = True + + [options.packages.find] + where = src + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup, find_namespace_packages + setup( + # ... , + packages=find_namespace_packages(where="src"), + package_dir={"": "src"}, + include_package_data=True, + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools] + # ... + # By default, include-package-data is true in pyproject.toml, so you do + # NOT have to specify this line. + include-package-data = true + + [tool.setuptools.packages.find] + # scanning for namespace packages is true by default in pyproject.toml, so + # you need NOT include the following line. + namespaces = true + where = ["src"] + +Summary +======= + +In summary, the three options allow you to: + +``include_package_data`` + Accept all data files and directories matched by |MANIFEST.in|_ or added by + a :ref:`plugin <Adding Support for Revision Control Systems>`. + +``package_data`` + Specify additional patterns to match files that may or may + not be matched by |MANIFEST.in|_ or added by + a :ref:`plugin <Adding Support for Revision Control Systems>`. + +``exclude_package_data`` + Specify patterns for data files and directories that should *not* be + included when a package is installed, even if they would otherwise have + been included due to the use of the preceding options. + +.. note:: + Due to the way the build process works, a data file that you + include in your project and then stop including may be "orphaned" in your + project's build directories, requiring you to run ``setup.py clean --all`` to + fully remove them. This may also be important for your users and contributors + if they track intermediate revisions of your project using Subversion; be sure + to let them know when you make changes that remove files from inclusion so they + can run ``setup.py clean --all``. + + +.. _Accessing Data Files at Runtime: + +Accessing Data Files at Runtime +=============================== + +Typically, existing programs manipulate a package's ``__file__`` attribute in +order to find the location of data files. For example, if you have a structure +like this:: + + project_root_directory + ├── setup.py # and/or setup.cfg, pyproject.toml + └── src + └── mypkg + ├── data + │ └── data1.txt + ├── __init__.py + └── foo.py + +Then, in ``mypkg/foo.py``, you may try something like this in order to access +``mypkg/data/data1.txt``: + +.. code-block:: python + + import os + data_path = os.path.join(os.path.dirname(__file__), 'data', 'data1.txt') + with open(data_path, 'r') as data_file: + ... + +However, this manipulation isn't compatible with :pep:`302`-based import hooks, +including importing from zip files and Python Eggs. It is strongly recommended that, +if you are using data files, you should use :mod:`importlib.resources` to access them. +In this case, you would do something like this: + +.. code-block:: python + + from importlib.resources import files + data_text = files('mypkg.data').joinpath('data1.txt').read_text() + +:mod:`importlib.resources` was added to Python 3.7. However, the API illustrated in +this code (using ``files()``) was added only in Python 3.9, [#files_api]_ and support +for accessing data files via namespace packages was added only in Python 3.10 [#namespace_support]_ +(the ``data`` subdirectory is a namespace package under the root package ``mypkg``). +Therefore, you may find this code to work only in Python 3.10 (and above). For other +versions of Python, you are recommended to use the :pypi:`importlib-resources` backport +which provides the latest version of this library. In this case, the only change that +has to be made to the above code is to replace ``importlib.resources`` with ``importlib_resources``, i.e. + +.. code-block:: python + + from importlib_resources import files + ... + +See :doc:`importlib-resources:using` for detailed instructions. + +.. tip:: Files inside the package directory should be *read-only* to avoid a + series of common problems (e.g. when multiple users share a common Python + installation, when the package is loaded from a zip file, or when multiple + instances of a Python application run in parallel). + + If your Python package needs to write to a file for shared data or configuration, + you can use standard platform/OS-specific system directories, such as + ``~/.local/config/$appname`` or ``/usr/share/$appname/$version`` (Linux specific) [#system-dirs]_. + A common approach is to add a read-only template file to the package + directory that is then copied to the correct system directory if no + pre-existing file is found. + + +Non-Package Data Files +====================== + +Historically, ``setuptools`` by way of ``easy_install`` would encapsulate data +files from the distribution into the egg (see `the old docs +<https://github.com/pypa/setuptools/blob/52aacd5b276fedd6849c3a648a0014f5da563e93/docs/setuptools.txt#L970-L1001>`_). As eggs are deprecated and pip-based installs +fall back to the platform-specific location for installing data files, there is +no supported facility to reliably retrieve these resources. + +Instead, the PyPA recommends that any data files you wish to be accessible at +run time be included **inside the package**. + + +---- + +.. [#beta] + Support for adding build configuration options via the ``[tool.setuptools]`` + table in the ``pyproject.toml`` file. See :doc:`/userguide/pyproject_config`. + +.. [#system-dirs] These locations can be discovered with the help of + third-party libraries such as :pypi:`platformdirs`. + +.. [#files_api] Reference: https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy + +.. [#namespace_support] Reference: https://github.com/python/importlib_resources/pull/196#issuecomment-734520374 + + +.. |MANIFEST.in| replace:: ``MANIFEST.in`` +.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/ diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst new file mode 100644 index 00000000..3ef7b074 --- /dev/null +++ b/docs/userguide/declarative_config.rst @@ -0,0 +1,318 @@ +.. _declarative config: + +------------------------------------------------ +Configuring setuptools using ``setup.cfg`` files +------------------------------------------------ + +.. note:: New in 30.3.0 (8 Dec 2016). + +.. important:: + If compatibility with legacy builds (i.e. those not using the :pep:`517` + build API) is desired, a ``setup.py`` file containing a ``setup()`` function + call is still required even if your configuration resides in ``setup.cfg``. + +``Setuptools`` allows using configuration files (usually :file:`setup.cfg`) +to define a package’s metadata and other options that are normally supplied +to the ``setup()`` function (declarative config). + +This approach not only allows automation scenarios but also reduces +boilerplate code in some cases. + +.. _example-setup-config: + +.. code-block:: ini + + [metadata] + name = my_package + version = attr: my_package.VERSION + description = My package description + long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst + keywords = one, two + license = BSD 3-Clause License + classifiers = + Framework :: Django + Programming Language :: Python :: 3 + + [options] + zip_safe = False + include_package_data = True + packages = find: + install_requires = + requests + importlib-metadata; python_version<"3.8" + + [options.package_data] + * = *.txt, *.rst + hello = *.msg + + [options.entry_points] + console_scripts = + executable-name = my_package.module:function + + [options.extras_require] + pdf = ReportLab>=1.2; RXP + rest = docutils>=0.3; pack ==1.1, ==1.3 + + [options.packages.find] + exclude = + examples* + tools* + docs* + my_package.tests* + +Metadata and options are set in the config sections of the same name. + +* Keys are the same as the :doc:`keyword arguments </references/keywords>` one + provides to the ``setup()`` function. + +* Complex values can be written comma-separated or placed one per line + in *dangling* config values. The following are equivalent: + + .. code-block:: ini + + [metadata] + keywords = one, two + + [metadata] + keywords = + one + two + +* In some cases, complex values can be provided in dedicated subsections for + clarity. + +* Some keys allow ``file:``, ``attr:``, ``find:``, and ``find_namespace:`` directives in + order to cover common usecases. + +* Unknown keys are ignored. + + +Using a ``src/`` layout +======================= + +One commonly used configuration has all the Python source code in a +subdirectory (often called the ``src/`` layout), like this:: + + ├── src + │ └── mypackage + │ ├── __init__.py + │ └── mod1.py + ├── setup.py + └── setup.cfg + +You can set up your ``setup.cfg`` to automatically find all your packages in +the subdirectory, using :ref:`package_dir <keyword/package_dir>`, like this: + +.. code-block:: ini + + # This example contains just the necessary options for a src-layout, set up + # the rest of the file as described above. + + [options] + package_dir= + =src + packages=find: + + [options.packages.find] + where=src + +In this example, the value for the :ref:`package_dir <keyword/package_dir>` +configuration (i.e. ``=src``) is parsed as ``{"": "src"}``. +The ``""`` key has a special meaning in this context, and indicates that all the +packages are contained inside the given directory. +Also note that the value for ``[options.packages.find] where`` matches the +value associated with ``""`` in the ``package_dir`` dictionary. + +.. + TODO: Add the following tip once the auto-discovery is no longer experimental: + + Starting in version 61, ``setuptools`` can automatically infer the + configurations for both ``packages`` and ``package_dir`` for projects using + a ``src/`` layout (as long as no value is specified for ``py_modules``). + Please see :doc:`package discovery </userguide/package_discovery>` for more + details. + +Specifying values +================= + +Some values are treated as simple strings, some allow more logic. + +Type names used below: + +* ``str`` - simple string +* ``list-comma`` - dangling list or string of comma-separated values +* ``list-semi`` - dangling list or string of semicolon-separated values +* ``bool`` - ``True`` is 1, yes, true +* ``dict`` - list-comma where each entry corresponds to a key/value pair, + with keys separated from values by ``=``. + If an entry starts with ``=``, the key is assumed to be an empty string + (e.g. ``=src`` is parsed as ``{"": "src"}``). +* ``section`` - values are read from a dedicated (sub)section + + +Special directives: + +* ``attr:`` - Value is read from a module attribute. ``attr:`` supports + callables and iterables; unsupported types are cast using ``str()``. + + In order to support the common case of a literal value assigned to a variable + in a module containing (directly or indirectly) third-party imports, + ``attr:`` first tries to read the value from the module by examining the + module's AST. If that fails, ``attr:`` falls back to importing the module. + +* ``file:`` - Value is read from a list of files and then concatenated + + .. important:: + The ``file:`` directive is sandboxed and won't reach anything outside the + project directory (i.e. the directory containing ``setup.cfg``/``pyproject.toml``). + + .. attention:: + When using the ``file:`` directive, please make sure that all necessary + files are included in the ``sdist``. You can do that via ``MANIFEST.in`` + or using plugins such as ``setuptools-scm``. + Please have a look on :doc:`/userguide/miscellaneous` for more information. + + +Metadata +-------- + +.. attention:: + The aliases given below are supported for compatibility reasons, + but their use is not advised. + +============================== ================= ================= =============== ========== +Key Aliases Type Minimum Version Notes +============================== ================= ================= =============== ========== +name str +version attr:, file:, str 39.2.0 [#meta-1]_ +url home-page str +download_url download-url str +project_urls dict 38.3.0 +author str +author_email author-email str +maintainer str +maintainer_email maintainer-email str +classifiers classifier file:, list-comma +license str +license_files license_file list-comma 42.0.0 +description summary file:, str +long_description long-description file:, str +long_description_content_type str 38.6.0 +keywords list-comma +platforms platform list-comma +provides list-comma +requires list-comma +obsoletes list-comma +============================== ================= ================= =============== ========== + +**Notes**: + +.. [#meta-1] The ``version`` file attribute has only been supported since 39.2.0. + + A version loaded using the ``file:`` directive must comply with PEP 440. + It is easy to accidentally put something other than a valid version + string in such a file, so validation is stricter in this case. + + +Options +------- + +======================= =================================== =============== ==================== +Key Type Minimum Version Notes +======================= =================================== =============== ==================== +zip_safe bool +setup_requires list-semi 36.7.0 +install_requires file:, list-semi **BETA** [#opt-6]_ +extras_require file:, section **BETA** [#opt-2]_, [#opt-6]_ +python_requires str 34.4.0 +entry_points file:, section 51.0.0 +scripts list-comma +eager_resources list-comma +dependency_links list-comma +tests_require list-semi +include_package_data bool +packages find:, find_namespace:, list-comma [#opt-3]_ +package_dir dict +package_data section [#opt-1]_ +exclude_package_data section +namespace_packages list-comma [#opt-5]_ +py_modules list-comma 34.4.0 +data_files section 40.6.0 [#opt-4]_ +======================= =================================== =============== ==================== + +**Notes**: + +.. [#opt-1] In the ``package_data`` section, a key named with a single asterisk + (``*``) refers to all packages, in lieu of the empty string used in ``setup.py``. + +.. [#opt-2] In the ``extras_require`` section, values are parsed as ``list-semi``. + This implies that in order to include markers, they **must** be *dangling*: + + .. code-block:: ini + + [options.extras_require] + rest = docutils>=0.3; pack ==1.1, ==1.3 + pdf = + ReportLab>=1.2 + RXP + importlib-metadata; python_version < "3.8" + +.. [#opt-3] The ``find:`` and ``find_namespace:`` directive can be further configured + in a dedicated subsection ``options.packages.find``. This subsection accepts the + same keys as the ``setuptools.find_packages`` and the + ``setuptools.find_namespace_packages`` function: + ``where``, ``include``, and ``exclude``. + + The ``find_namespace:`` directive is supported since Python >=3.3. + +.. [#opt-4] ``data_files`` is deprecated and should be avoided. + Please check :doc:`/userguide/datafiles` for more information. + +.. [#opt-5] ``namespace_packages`` is deprecated in favour of native/implicit + namespaces (:pep:`420`). Check :doc:`the Python Packaging User Guide + <PyPUG:guides/packaging-namespace-packages>` for more information. + +.. [#opt-6] ``file:`` directives for reading requirements are supported since version 62.6. + The format for the file resembles a ``requirements.txt`` file, + however please keep in mind that all non-comment lines must conform with :pep:`508` + (``pip``-specify syntaxes, e.g. ``-c/-r/-e`` flags, are not supported). + Library developers should avoid tightly pinning their dependencies to a specific + version (e.g. via a "locked" requirements file). + + +Compatibility with other tools +============================== + +Historically, several tools explored declarative package configuration +in parallel. And several of them chose to place the packaging +configuration within the project's :file:`setup.cfg` file. +One of the first was ``distutils2``, which development has stopped in +2013. Other include ``pbr`` which is still under active development or +``d2to1``, which was a plug-in that backports declarative configuration +to ``distutils``, but has had no release since Oct. 2015. +As a way to harmonize packaging tools, ``setuptools``, having held the +position of *de facto* standard, has gradually integrated those +features as part of its core features. + +Still this has lead to some confusion and feature incompatibilities: + +- some tools support features others don't; +- some have similar features but the declarative syntax differs; + +The table below tries to summarize the differences. But, please, refer +to each tool documentation for up-to-date information. + +=========================== ========== ========== ===== === +feature setuptools distutils2 d2to1 pbr +=========================== ========== ========== ===== === +[metadata] description-file S Y Y Y +[files] S Y Y Y +entry_points Y Y Y S +[backwards_compat] N Y Y Y +=========================== ========== ========== ===== === + +Y: supported, N: unsupported, S: syntax differs (see +:ref:`above example<example-setup-config>`). + +Also note that some features were only recently added to ``setuptools``. +Please refer to the previous sections to find out when. diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst new file mode 100644 index 00000000..33aaf6c6 --- /dev/null +++ b/docs/userguide/dependency_management.rst @@ -0,0 +1,422 @@ +===================================== +Dependencies Management in Setuptools +===================================== + +There are three types of dependency styles offered by setuptools: +1) build system requirement, 2) required dependency and 3) optional +dependency. + +Each dependency, regardless of type, needs to be specified according to :pep:`508` +and :pep:`440`. +This allows adding version :pep:`range restrictions <440#version-specifiers>` +and :ref:`environment markers <environment-markers>`. + + +.. _build-requires: + +Build system requirement +======================== + +After organizing all the scripts and files and getting ready for packaging, +there needs to be a way to specify what programs and libraries are actually needed +do the packaging (in our case, ``setuptools`` of course). +This needs to be specified in your ``pyproject.toml`` file +(if you have forgot what this is, go to :doc:`/userguide/quickstart` or :doc:`/build_meta`): + +.. code-block:: toml + + [build-system] + requires = ["setuptools"] + #... + +Please note that you should also include here any other ``setuptools`` plugin +(e.g., :pypi:`setuptools-scm`, :pypi:`setuptools-golang`, :pypi:`setuptools-rust`) +or build-time dependency (e.g., :pypi:`Cython`, :pypi:`cppy`, :pypi:`pybind11`). + +.. note:: + In previous versions of ``setuptools``, + this used to be accomplished with the ``setup_requires`` keyword but is + now considered deprecated in favor of the :pep:`517` style described above. + To peek into how this legacy keyword is used, consult our :doc:`guide on + deprecated practice (WIP) </deprecated/index>`. + + +.. _Declaring Dependencies: + +Declaring required dependency +============================= +This is where a package declares its core dependencies, without which it won't +be able to run. ``setuptools`` supports automatically downloading and installing +these dependencies when the package is installed. Although there is more +finesse to it, let's start with a simple example. + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "docutils", + "BazSpam == 1.1", + ] + # ... + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + #... + install_requires = + docutils + BazSpam ==1.1 + +.. tab:: setup.py + + .. code-block:: python + + setup( + ..., + install_requires=[ + 'docutils', + 'BazSpam ==1.1', + ], + ) + + +When your project is installed (e.g., using :pypi:`pip`), all of the dependencies not +already installed will be located (via `PyPI`_), downloaded, built (if necessary), +and installed and 2) Any scripts in your project will be installed with wrappers +that verify the availability of the specified dependencies at runtime. + + +.. _environment-markers: + +Platform specific dependencies +------------------------------ +Setuptools offers the capability to evaluate certain conditions before blindly +installing everything listed in ``install_requires``. This is great for platform +specific dependencies. For example, the ``enum`` package was added in Python +3.4, therefore, package that depends on it can elect to install it only when +the Python version is older than 3.4. To accomplish this + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "enum34; python_version<'3.4'", + ] + # ... + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + #... + install_requires = + enum34;python_version<'3.4' + +.. tab:: setup.py + + .. code-block:: python + + setup( + ..., + install_requires=[ + "enum34;python_version<'3.4'", + ], + ) + +Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0 +and only install it if the user is using a Windows operating system: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "enum34; python_version<'3.4'", + "pywin32 >= 1.0; platform_system=='Windows'", + ] + # ... + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + #... + install_requires = + enum34;python_version<'3.4' + pywin32 >= 1.0;platform_system=='Windows' + +.. tab:: setup.py + + .. code-block:: python + + setup( + ..., + install_requires=[ + "enum34;python_version<'3.4'", + "pywin32 >= 1.0;platform_system=='Windows'", + ], + ) + +The environmental markers that may be used for testing platform types are +detailed in :pep:`508`. + +.. seealso:: + If environment markers are not enough an specific use case, + you can also consider creating a :ref:`backend wrapper <backend-wrapper>` + to implement custom detection logic. + + +Direct URL dependencies +----------------------- + +.. attention:: + `PyPI`_ and other standards-conformant package indices **do not** accept + packages that declare dependencies using direct URLs. ``pip`` will accept them + when installing packages from the local filesystem or from another URL, + however. + +Dependencies that are not available on a package index but can be downloaded +elsewhere in the form of a source repository or archive may be specified +using a variant of :pep:`PEP 440's direct references <440#direct-references>`: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "Package-A @ git+https://example.net/package-a.git@main", + "Package-B @ https://example.net/archives/package-b.whl", + ] + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + #... + install_requires = + Package-A @ git+https://example.net/package-a.git@main + Package-B @ https://example.net/archives/package-b.whl + +.. tab:: setup.py + + .. code-block:: python + + setup( + install_requires=[ + "Package-A @ git+https://example.net/package-a.git@main", + "Package-B @ https://example.net/archives/package-b.whl", + ], + ..., + ) + +For source repository URLs, a list of supported protocols and VCS-specific +features such as selecting certain branches or tags can be found in pip's +documentation on `VCS support <https://pip.pypa.io/en/latest/topics/vcs-support/>`_. +Supported formats for archive URLs are sdists and wheels. + + +Optional dependencies +===================== +Setuptools allows you to declare dependencies that are not installed by default. +This effectively means that you can create a "variant" of your package with a +set of extra functionalities. + +For example, let's consider a ``Package-A`` that offers +optional PDF support and requires two other dependencies for it to work: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + name = "Package-A" + # ... + [project.optional-dependencies] + PDF = ["ReportLab>=1.2", "RXP"] + +.. tab:: setup.cfg + + .. code-block:: ini + + [metadata] + name = Package-A + + [options.extras_require] + PDF = + ReportLab>=1.2 + RXP + + +.. tab:: setup.py + + .. code-block:: python + + setup( + name="Package-A", + ..., + extras_require={ + "PDF": ["ReportLab>=1.2", "RXP"], + }, + ) + +.. sidebar:: + + .. tip:: + It is also convenient to declare optional requirements for + ancillary tasks such as running tests and or building docs. + +The name ``PDF`` is an arbitrary :pep:`identifier <685>` of such a list of dependencies, to +which other components can refer and have them installed. + +A use case for this approach is that other package can use this "extra" for their +own dependencies. For example, if ``Package-B`` needs ``Package-A`` with PDF support +installed, it might declare the dependency like this: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + name = "Package-B" + # ... + dependencies = [ + "Package-A[PDF]" + ] + +.. tab:: setup.cfg + + .. code-block:: ini + + [metadata] + name = Package-B + #... + + [options] + #... + install_requires = + Package-A[PDF] + +.. tab:: setup.py + + .. code-block:: python + + setup( + name="Package-B", + install_requires=["Package-A[PDF]"], + ..., + ) + +This will cause ``ReportLab`` to be installed along with ``Package-A``, if ``Package-B`` is +installed -- even if ``Package-A`` was already installed. In this way, a project +can encapsulate groups of optional "downstream dependencies" under a feature +name, so that packages that depend on it don't have to know what the downstream +dependencies are. If a later version of ``Package-A`` builds in PDF support and +no longer needs ``ReportLab``, or if it ends up needing other dependencies besides +``ReportLab`` in order to provide PDF support, ``Package-B``'s setup information does +not need to change, but the right packages will still be installed if needed. + +.. tip:: + Best practice: if a project ends up no longer needing any other packages to + support a feature, it should keep an empty requirements list for that feature + in its ``extras_require`` argument, so that packages depending on that feature + don't break (due to an invalid feature name). + +.. warning:: + Historically ``setuptools`` also used to support extra dependencies in console + scripts, for example: + + .. tab:: setup.cfg + + .. code-block:: ini + + [metadata] + name = Package-A + #... + + [options] + #... + entry_points= + [console_scripts] + rst2pdf = project_a.tools.pdfgen [PDF] + rst2html = project_a.tools.htmlgen + + .. tab:: setup.py + + .. code-block:: python + + setup( + name="Package-A", + ..., + entry_points={ + "console_scripts": [ + "rst2pdf = project_a.tools.pdfgen [PDF]", + "rst2html = project_a.tools.htmlgen", + ], + }, + ) + + This syntax indicates that the entry point (in this case a console script) + is only valid when the PDF extra is installed. It is up to the installer + to determine how to handle the situation where PDF was not indicated + (e.g., omit the console script, provide a warning when attempting to load + the entry point, assume the extras are present and let the implementation + fail later). + + **However**, ``pip`` and other tools might not support this use case for extra + dependencies, therefore this practice is considered **deprecated**. + See :doc:`PyPUG:specifications/entry-points`. + + +Python requirement +================== +In some cases, you might need to specify the minimum required python version. +This can be configured as shown in the example below. + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + name = "Package-B" + requires-python = ">=3.6" + # ... + +.. tab:: setup.cfg + + .. code-block:: ini + + [metadata] + name = Package-B + #... + + [options] + #... + python_requires = >=3.6 + +.. tab:: setup.py + + .. code-block:: python + + setup( + name="Package-B", + python_requires=">=3.6", + ..., + ) + + +.. _PyPI: https://pypi.org diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst new file mode 100644 index 00000000..6f9f5417 --- /dev/null +++ b/docs/userguide/development_mode.rst @@ -0,0 +1,271 @@ +Development Mode (a.k.a. "Editable Installs") +============================================= + +When creating a Python project, developers usually want to implement and test +changes iteratively, before cutting a release and preparing a distribution archive. + +In normal circumstances this can be quite cumbersome and require the developers +to manipulate the ``PYTHONPATH`` environment variable or to continuously re-build +and re-install the project. + +To facilitate iterative exploration and experimentation, setuptools allows +users to instruct the Python interpreter and its import machinery to load the +code under development directly from the project folder without having to +copy the files to a different location in the disk. +This means that changes in the Python source code can immediately take place +without requiring a new installation. + +You can enter this "development mode" by performing an :doc:`editable installation +<pip:topics/local-project-installs>` inside of a :term:`virtual environment`, +using :doc:`pip's <pip:cli/pip_install>` ``-e/--editable`` flag, as shown below: + +.. code-block:: bash + + $ cd your-python-project + $ python -m venv .venv + # Activate your environemt with: + # `source .venv/bin/activate` on Unix/macOS + # or `.venv\Scripts\activate` on Windows + + $ pip install --editable . + + # Now you have access to your package + # as if it was installed in .venv + $ python -c "import your_python_project" + + +An "editable installation" works very similarly to a regular install with +``pip install .``, except that it only installs your package dependencies, +metadata and wrappers for :ref:`console and GUI scripts <console-scripts>`. +Under the hood, setuptools will try to create a special :mod:`.pth file <site>` +in the target directory (usually ``site-packages``) that extends the +``PYTHONPATH`` or install a custom :doc:`import hook <python:reference/import>`. + +When you're done with a given development task, you can simply uninstall your +package (as you would normally do with ``pip uninstall <package name>``). + +Please note that, by default an editable install will expose at least all the +files that would be available in a regular installation. However, depending on +the file and directory organization in your project, it might also expose +as a side effect files that would not be normally available. +This is allowed so you can iteratively create new Python modules. +Please have a look on the following section if you are looking for a different behaviour. + +.. admonition:: Virtual Environments + + You can think about virtual environments as "isolated Python runtime deployments" + that allow users to install different sets of libraries and tools without + messing with the global behaviour of the system. + + They are a safe way of testing new projects and can be created easily + with the :mod:`venv` module from the standard library. + + Please note however that depending on your operating system or distribution, + ``venv`` might not come installed by default with Python. For those cases, + you might need to use the OS package manager to install it. + For example, in Debian/Ubuntu-based systems you can obtain it via: + + .. code-block:: bash + + sudo apt install python3-venv + + Alternatively, you can also try installing :pypi:`virtualenv`. + More information is available on the Python Packaging User Guide on + :doc:`PyPUG:guides/installing-using-pip-and-virtual-environments`. + +.. note:: + .. versionchanged:: v64.0.0 + Editable installation hooks implemented according to :pep:`660`. + Support for :pep:`namespace packages <420>` is still **EXPERIMENTAL**. + + +"Strict" editable installs +-------------------------- + +When thinking about editable installations, users might have the following +expectations: + +1. It should allow developers to add new files (or split/rename existing ones) + and have them automatically exposed. +2. It should behave as close as possible to a regular installation and help + users to detect problems (e.g. new files not being included in the distribution). + +Unfortunately these expectations are in conflict with each other. +To solve this problem ``setuptools`` allows developers to choose a more +*"strict"* mode for the editable installation. This can be done by passing +a special *configuration setting* via :pypi:`pip`, as indicated below: + +.. code-block:: bash + + pip install -e . --config-settings editable_mode=strict + +In this mode, new files **won't** be exposed and the editable installs will +try to mimic as much as possible the behavior of a regular install. +Under the hood, ``setuptools`` will create a tree of file links in an auxiliary +directory (``$your_project_dir/build``) and add it to ``PYTHONPATH`` via a +:mod:`.pth file <site>`. (Please be careful to not delete this repository +by mistake otherwise your files may stop being accessible). + +.. warning:: + Strict editable installs require auxiliary files to be placed in a + ``build/__editable__.*`` directory (relative to your project root). + + Please be careful to not remove this directory while testing your project, + otherwise your editable installation may be compromised. + + You can remove the ``build/__editable__.*`` directory after uninstalling. + + +.. note:: + .. versionadded:: v64.0.0 + Added new *strict* mode for editable installations. + The exact details of how this mode is implemented may vary. + + +Limitations +----------- + +- The *editable* term is used to refer only to Python modules + inside the package directories. Non-Python files, external (data) files, + executable script files, binary extensions, headers and metadata may be + exposed as a *snapshot* of the version they were at the moment of the + installation. +- Adding new dependencies, entry-points or changing your project's metadata + require a fresh "editable" re-installation. +- Console scripts and GUI scripts **MUST** be specified via :doc:`entry-points + </userguide/entry_point>` to work properly. +- *Strict* editable installs require the file system to support + either :wiki:`symbolic <symbolic link>` or :wiki:`hard links <hard link>`. + This installation mode might also generate auxiliary files under the project directory. +- There is *no guarantee* that the editable installation will be performed + using a specific technique. Depending on each project, ``setuptools`` may + select a different approach to ensure the package is importable at runtime. +- There is *no guarantee* that files outside the top-level package directory + will be accessible after an editable install. +- There is *no guarantee* that attributes like ``__path__`` or ``__file__`` + will correspond to the exact location of the original files (e.g., + ``setuptools`` might employ file links to perform the editable installation). + Users are encouraged to use tools like :mod:`importlib.resources` or + :mod:`importlib.metadata` when trying to access package files directly. +- Editable installations may not work with + :doc:`namespaces created with pkgutil or pkg_resources + <PyPUG:guides/packaging-namespace-packages>`. + Please use :pep:`420`-style implicit namespaces [#namespaces]_. +- Support for :pep:`420`-style implicit namespace packages for + projects structured using :ref:`flat-layout` is still **experimental**. + If you experience problems, you can try converting your package structure + to the :ref:`src-layout`. +- File system entries in the current working directory + whose names coincidentally match installed packages + may take precedence in :doc:`Python's import system <python:reference/import>`. + Users are encouraged to avoid such scenarios [#cwd]_. + +.. attention:: + Editable installs are **not a perfect replacement for regular installs** + in a test environment. When in doubt, please test your projects as + installed via a regular wheel. There are tools in the Python ecosystem, + like :pypi:`tox` or :pypi:`nox`, that can help you with that + (when used with appropriate configuration). + + +Legacy Behavior +--------------- + +If your project is not compatible with the new "editable installs" or you wish +to replicate the legacy behavior, for the time being you can also perform the +installation in the ``compat`` mode: + +.. code-block:: bash + + pip install -e . --config-settings editable_mode=compat + +This installation mode will try to emulate how ``python setup.py develop`` +works (still within the context of :pep:`660`). + +.. warning:: + The ``compat`` mode is *transitional* and will be removed in + future versions of ``setuptools``, it exists only to help during the + migration period. + Also note that support for this mode is limited: + it is safe to assume that the ``compat`` mode is offered "as is", and + improvements are unlikely to be implemented. + Users are encouraged to try out the new editable installation techniques + and make the necessary adaptations. + +If the ``compat`` mode does not work for you, you can also disable the +:pep:`editable install <660>` hooks in ``setuptools`` by setting an environment +variable: + +.. code-block:: + + SETUPTOOLS_ENABLE_FEATURES="legacy-editable" + +This *may* cause the installer (e.g. ``pip``) to effectively run the "legacy" +installation command: ``python setup.py develop`` [#installer]_. + + +How editable installations work +------------------------------- + +*Advanced topic* + +There are many techniques that can be used to expose packages under development +in such a way that they are available as if they were installed. +Depending on the project file structure and the selected mode, ``setuptools`` +will choose one of these approaches for the editable installation [#criteria]_. + +A non-exhaustive list of implementation mechanisms is presented below. +More information is available on the text of :pep:`PEP 660 <660#what-to-put-in-the-wheel>`. + +- A static ``.pth`` file [#static_pth]_ can be added to one of the directories + listed in :func:`site.getsitepackages` or :func:`site.getusersitepackages` to + extend :obj:`sys.path`. +- A directory containing a *farm of file links* that mimic the + project structure and point to the original files can be employed. + This directory can then be added to :obj:`sys.path` using a static ``.pth`` file. +- A dynamic ``.pth`` file [#dynamic_pth]_ can also be used to install an + "import :term:`finder`" (:obj:`~importlib.abc.MetaPathFinder` or + :obj:`~importlib.abc.PathEntryFinder`) that will hook into Python's + :doc:`import system <python:reference/import>` machinery. + +.. attention:: + ``Setuptools`` offers **no guarantee** of which technique will be used to + perform an editable installation. This will vary from project to project + and may change depending on the specific version of ``setuptools`` being + used. + + +---- + +.. rubric:: Notes + +.. [#namespaces] + You *may* be able to use *strict* editable installations with namespace + packages created with ``pkgutil`` or ``pkg_namespaces``, however this is not + officially supported. + +.. [#cwd] + Techniques like the :ref:`src-layout` or tooling-specific options like + `tox's changedir <https://tox.wiki/en/stable/config.html#conf-changedir>`_ + can be used to prevent such kinds of situations (checkout `this blog post + <https://blog.ganssle.io/articles/2019/08/test-as-installed.html>`_ for more + insights). + +.. [#installer] + For this workaround to work, the installer tool needs to support legacy + editable installations. (Future versions of ``pip``, for example, may drop + support for this feature). + +.. [#criteria] + ``setuptools`` strives to find a balance between allowing the user to see + the effects of project files being edited while still trying to keep the + editable installation as similar as possible to a regular installation. + +.. [#static_pth] + i.e., a ``.pth`` file where each line correspond to a path that should be + added to :obj:`sys.path`. See :mod:`Site-specific configuration hook <site>`. + +.. [#dynamic_pth] + i.e., a ``.pth`` file that starts where each line starts with an ``import`` + statement and executes arbitrary Python code. See :mod:`Site-specific + configuration hook <site>`. diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst new file mode 100644 index 00000000..ae2dc4a4 --- /dev/null +++ b/docs/userguide/distribution.rst @@ -0,0 +1,198 @@ +.. _Specifying Your Project's Version: + +Specifying Your Project's Version +================================= + +Setuptools can work well with most versioning schemes. Over the years, +setuptools has tried to closely follow the :pep:`440` scheme, but it +also supports legacy versions. There are, however, a +few special things to watch out for, in order to ensure that setuptools and +other tools can always tell what version of your package is newer than another +version. Knowing these things will also help you correctly specify what +versions of other projects your project depends on. + +A version consists of an alternating series of release numbers and +`pre-release <https://peps.python.org/pep-0440/#pre-releases>`_ +or `post-release <https://peps.python.org/pep-0440/#post-releases>`_ tags. A +release number is a series of digits punctuated by +dots, such as ``2.4`` or ``0.5``. Each series of digits is treated +numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the +same release number, denoting the first subrelease of release 2. But ``2.10`` +is the *tenth* subrelease of release 2, and so is a different and newer release +from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also +ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``. + +Following a release number, you can have either a pre-release or post-release +tag. Pre-release tags make a version be considered *older* than the version +they are appended to. So, revision ``2.4`` is *newer* than release candidate +``2.4rc1``, which in turn is newer than beta release ``2.4b1`` or +alpha release ``2.4a1``. Postrelease tags make +a version be considered *newer* than the version they are appended to. So, +revisions like ``2.4.post1`` are newer than ``2.4``, but *older* +than ``2.4.1`` (which has a higher release number). + +In the case of legacy versions (for example, ``2.4pl1``), they are considered +older than non-legacy versions. Taking that in count, a revision ``2.4pl1`` +is *older* than ``2.4``. Note that ``2.4pl1`` is not :pep:`440`-compliant. + +A pre-release tag is a series of letters that are alphabetically before +"final". Some examples of prerelease tags would include ``alpha``, ``beta``, +``a``, ``c``, ``dev``, and so on. You do not have to place a dot or dash +before the prerelease tag if it's immediately after a number, but it's okay to +do so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` and ``2.4-c1`` all +represent release candidate 1 of version ``2.4``, and are treated as identical +by setuptools. Note that only ``a``, ``b``, and ``rc`` are :pep:`440`-compliant +pre-release tags. + +In addition, there are three special prerelease tags that are treated as if +they were ``rc``: ``c``, ``pre``, and ``preview``. So, version +``2.4c1``, ``2.4pre1`` and ``2.4preview1`` are all the exact same version as +``2.4rc1``, and are treated as identical by setuptools. + +A post-release tag is the string ``.post``, followed by a non-negative integer +value. Post-release tags are generally used to separate patch numbers, port +numbers, build numbers, revision numbers, or date stamps from the release +number. For example, the version ``2.4.post1263`` might denote Subversion +revision 1263 of a post-release patch of version ``2.4``. Or you might use +``2.4.post20051127`` to denote a date-stamped post-release. Legacy post-release +tags could be either a series of letters that are alphabetically greater than or +equal to "final", or a dash (``-``) - for example ``2.4-r1263`` or +``2.4-20051127``. + +Notice that after each legacy pre or post-release tag, you are free to place +another release number, followed again by more pre- or post-release tags. For +example, ``0.6a9.dev41475`` could denote Subversion revision 41475 of the in- +development version of the ninth alpha of release 0.6. Notice that ``dev`` is +a pre-release tag, so this version is a *lower* version number than ``0.6a9``, +which would be the actual ninth alpha of release 0.6. But the ``41475`` is +a post-release tag, so this version is *newer* than ``0.6a9.dev``. + +For the most part, setuptools' interpretation of version numbers is intuitive, +but here are a few tips that will keep you out of trouble in the corner cases: + +* Don't stick adjoining pre-release tags together without a dot or number + between them. Version ``1.9adev`` is the ``adev`` prerelease of ``1.9``, + *not* a development pre-release of ``1.9a``. Use ``.dev`` instead, as in + ``1.9a.dev``, or separate the prerelease tags with a number, as in + ``1.9a0dev``. ``1.9a.dev``, ``1.9a0dev``, and even ``1.9a0.dev0`` are + identical versions from setuptools' point of view, so you can use whatever + scheme you prefer. Of these examples, only ``1.9a0.dev0`` is + :pep:`440`-compliant. + +* If you want to be certain that your chosen numbering scheme works the way + you think it will, you can use the ``pkg_resources.parse_version()`` function + to compare different version numbers:: + + >>> from pkg_resources import parse_version + >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev") + True + >>> parse_version("2.1-rc2") < parse_version("2.1") + True + >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9") + True + +Once you've decided on a version numbering scheme for your project, you can +have setuptools automatically tag your in-development releases with various +pre- or post-release tags. See the following section for more details. + + +Tagging and "Daily Build" or "Snapshot" Releases +------------------------------------------------ + +.. warning:: + Please note that running ``python setup.py ...`` directly is no longer + considered a good practice and that in the future the commands ``egg_info`` + and ``rotate`` will be deprecated. + + As a result, the instructions and information presented in this section + should be considered **transitional** while setuptools don't provide a + mechanism for tagging releases. + + Meanwhile, if you can also consider using :pypi:`setuptools-scm` to achieve + similar objectives. + + +When a set of related projects are under development, it may be important to +track finer-grained version increments than you would normally use for e.g. +"stable" releases. While stable releases might be measured in dotted numbers +with alpha/beta/etc. status codes, development versions of a project often +need to be tracked by revision or build number or even build date. This is +especially true when projects in development need to refer to one another, and +therefore may literally need an up-to-the-minute version of something! + +To support these scenarios, ``setuptools`` allows you to "tag" your source and +egg distributions by adding one or more of the following to the project's +"official" version identifier: + +* A manually-specified pre-release tag, such as "build" or "dev", or a + manually-specified post-release tag, such as a build or revision number + (``--tag-build=STRING, -bSTRING``) + +* An 8-character representation of the build date (``--tag-date, -d``), as + a postrelease tag + +You can add these tags by adding ``egg_info`` and the desired options to +the command line ahead of the ``sdist`` or ``bdist`` commands that you want +to generate a daily build or snapshot for. See the section below on the +:ref:`egg_info <egg_info>` command for more details. + +(Also, before you release your project, be sure to see the section on +:ref:`Specifying Your Project's Version` for more information about how pre- and +post-release tags affect how version numbers are interpreted. This is +important in order to make sure that dependency processing tools will know +which versions of your project are newer than others). + +Finally, if you are creating builds frequently, and either building them in a +downloadable location or are copying them to a distribution server, you should +probably also check out the :ref:`rotate <rotate>` command, which lets you automatically +delete all but the N most-recently-modified distributions matching a glob +pattern. So, you can use a command line like:: + + setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3 + +to build an egg whose version info includes "DEV-rNNNN" (where NNNN is the +most recent Subversion revision that affected the source tree), and then +delete any egg files from the distribution directory except for the three +that were built most recently. + +If you have to manage automated builds for multiple packages, each with +different tagging and rotation policies, you may also want to check out the +:ref:`alias <alias>` command, which would let each package define an alias like ``daily`` +that would perform the necessary tag, build, and rotate commands. Then, a +simpler script or cron job could just run ``setup.py daily`` in each project +directory. (And, you could also define sitewide or per-user default versions +of the ``daily`` alias, so that projects that didn't define their own would +use the appropriate defaults.) + +Making "Official" (Non-Snapshot) Releases +----------------------------------------- + +When you make an official release, creating source or binary distributions, +you will need to override the tag settings from ``setup.cfg``, so that you +don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is +easy to do if you are developing on the trunk and using tags or branches for +your releases - just make the change to ``setup.cfg`` after branching or +tagging the release, so the trunk will still produce development snapshots. + +Alternately, if you are not branching for releases, you can override the +default version options on the command line, using something like:: + + setup.py egg_info -Db "" sdist bdist_egg + +The first part of this command (``egg_info -Db ""``) will override the +configured tag information, before creating source and binary eggs. Thus, these +commands will use the plain version from your ``setup.py``, without adding the +build designation string. + +Of course, if you will be doing this a lot, you may wish to create a personal +alias for this operation, e.g.:: + + setup.py alias -u release egg_info -Db "" + +You can then use it like this:: + + setup.py release sdist bdist_egg + +Or of course you can create more elaborate aliases that do all of the above. +See the sections below on the :ref:`egg_info <egg_info>` and +:ref:`alias <alias>` commands for more ideas. diff --git a/docs/userguide/entry_point.rst b/docs/userguide/entry_point.rst new file mode 100644 index 00000000..163ce1d9 --- /dev/null +++ b/docs/userguide/entry_point.rst @@ -0,0 +1,571 @@ +.. _`entry_points`: + +============ +Entry Points +============ + +Entry points are a type of metadata that can be exposed by packages on installation. +They are a very useful feature of the Python ecosystem, +and come specially handy in two scenarios: + +1. The package would like to provide commands to be run at the terminal. +This functionality is known as *console* scripts. The command may also +open up a GUI, in which case it is known as a *GUI* script. An example +of a console script is the one provided by the :pypi:`pip` package, which +allows you to run commands like ``pip install`` in the terminal. + +2. A package would like to enable customization of its functionalities +via *plugins*. For example, the test framework :pypi:`pytest` allows +customization via the ``pytest11`` entry point, and the syntax +highlighting tool :pypi:`pygments` allows specifying additional styles +using the entry point ``pygments.styles``. + + +.. _console-scripts: + +Console Scripts +=============== + +Let us start with console scripts. +First consider an example without entry points. Imagine a package +defined thus:: + + project_root_directory + ├── pyproject.toml # and/or setup.cfg, setup.py + └── src + └── timmins + ├── __init__.py + └── ... + +with ``__init__.py`` as: + +.. code-block:: python + + def hello_world(): + print("Hello world") + +Now, suppose that we would like to provide some way of executing the +function ``hello_world()`` from the command-line. One way to do this +is to create a file ``src/timmins/__main__.py`` providing a hook as +follows: + +.. code-block:: python + + from . import hello_world + + if __name__ == '__main__': + hello_world() + +Then, after installing the package ``timmins``, we may invoke the ``hello_world()`` +function as follows, through the `runpy <https://docs.python.org/3/library/runpy.html>`_ +module: + +.. code-block:: bash + + $ python -m timmins + Hello world + +Instead of this approach using ``__main__.py``, you can also create a +user-friendly CLI executable that can be called directly without ``python -m``. +In the above example, to create a command ``hello-world`` that invokes +``timmins.hello_world``, add a console script entry point to your +configuration: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.scripts] + hello-world = "timmins:hello_world" + +.. tab:: setup.cfg + + .. code-block:: ini + + [options.entry_points] + console_scripts = + hello-world = timmins:hello_world + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup + + setup( + # ..., + entry_points={ + 'console_scripts': [ + 'hello-world = timmins:hello_world', + ] + } + ) + + +After installing the package, a user may invoke that function by simply calling +``hello-world`` on the command line: + +.. code-block:: bash + + $ hello-world + Hello world + +Note that any function configured as a console script, i.e. ``hello_world()`` in +this example, should not accept any arguments. If your function requires any input +from the user, you can use regular command-line argument parsing utilities like +:mod:`argparse` within the body of +the function to parse user input given via :obj:`sys.argv`. + +You may have noticed that we have used a special syntax to specify the function +that must be invoked by the console script, i.e. we have written ``timmins:hello_world`` +with a colon ``:`` separating the package name and the function name. The full +specification of this syntax is discussed in the `last section <#entry-points-syntax>`_ +of this document, and this can be used to specify a function located anywhere in +your package, not just in ``__init__.py``. + +GUI Scripts +=========== + +In addition to ``console_scripts``, Setuptools supports ``gui_scripts``, which +will launch a GUI application without running in a terminal window. + +For example, if we have a project with the same directory structure as before, +with an ``__init__.py`` file containing the following: + +.. code-block:: python + + import PySimpleGUI as sg + + def hello_world(): + sg.Window(title="Hello world", layout=[[]], margins=(100, 50)).read() + +Then, we can add a GUI script entry point: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.gui-scripts] + hello-world = "timmins:hello_world" + +.. tab:: setup.cfg + + .. code-block:: ini + + [options.entry_points] + gui_scripts = + hello-world = timmins:hello_world + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup + + setup( + # ..., + entry_points={ + 'gui_scripts': [ + 'hello-world = timmins:hello_world', + ] + } + ) + +.. note:: + To be able to import ``PySimpleGUI``, you need to add ``pysimplegui`` to your package dependencies. + See :doc:`/userguide/dependency_management` for more information. + +Now, running: + +.. code-block:: bash + + $ hello-world + +will open a small application window with the title 'Hello world'. + +Note that just as with console scripts, any function configured as a GUI script +should not accept any arguments, and any user input can be parsed within the +body of the function. GUI scripts also use the same syntax (discussed in the +`last section <#entry-points-syntax>`_) for specifying the function to be invoked. + +.. note:: + + The difference between ``console_scripts`` and ``gui_scripts`` only affects + Windows systems. [#use_for_scripts]_ ``console_scripts`` are wrapped in a console + executable, so they are attached to a console and can use ``sys.stdin``, + ``sys.stdout`` and ``sys.stderr`` for input and output. ``gui_scripts`` are + wrapped in a GUI executable, so they can be started without a console, but + cannot use standard streams unless application code redirects them. Other + platforms do not have the same distinction. + +.. note:: + + Console and GUI scripts work because behind the scenes, installers like :pypi:`pip` + create wrapper scripts around the function(s) being invoked. For example, + the ``hello-world`` entry point in the above two examples would create a + command ``hello-world`` launching a script like this: [#use_for_scripts]_ + + .. code-block:: python + + import sys + from timmins import hello_world + sys.exit(hello_world()) + +.. _dynamic discovery of services and plugins: + +Advertising Behavior +==================== + +Console/GUI scripts are one use of the more general concept of entry points. Entry +points more generally allow a packager to advertise behavior for discovery by +other libraries and applications. This feature enables "plug-in"-like +functionality, where one library solicits entry points and any number of other +libraries provide those entry points. + +A good example of this plug-in behavior can be seen in +`pytest plugins <https://docs.pytest.org/en/latest/writing_plugins.html>`_, +where pytest is a test framework that allows other libraries to extend +or modify its functionality through the ``pytest11`` entry point. + +The console/GUI scripts work similarly, where libraries advertise their commands +and tools like ``pip`` create wrapper scripts that invoke those commands. + +Entry Points for Plugins +======================== + +Let us consider a simple example to understand how we can implement entry points +corresponding to plugins. Say we have a package ``timmins`` with the following +directory structure:: + + timmins + ├── pyproject.toml # and/or setup.cfg, setup.py + └── src + └── timmins + └── __init__.py + +and in ``src/timmins/__init__.py`` we have the following code: + +.. code-block:: python + + def hello_world(): + print('Hello world') + +Basically, we have defined a ``hello_world()`` function which will print the text +'Hello world'. Now, let us say we want to print the text 'Hello world' in different +ways. The current function just prints the text as it is - let us say we want another +style in which the text is enclosed within exclamation marks:: + + !!! Hello world !!! + +Let us see how this can be done using plugins. First, let us separate the style of +printing the text from the text itself. In other words, we can change the code in +``src/timmins/__init__.py`` to something like this: + +.. code-block:: python + + def display(text): + print(text) + + def hello_world(): + display('Hello world') + +Here, the ``display()`` function controls the style of printing the text, and the +``hello_world()`` function calls the ``display()`` function to print the text 'Hello +world`. + +Right now the ``display()`` function just prints the text as it is. In order to be able +to customize it, we can do the following. Let us introduce a new *group* of entry points +named ``timmins.display``, and expect plugin packages implementing this entry point +to supply a ``display()``-like function. Next, to be able to automatically discover plugin +packages that implement this entry point, we can use the +:mod:`importlib.metadata` module, +as follows: + +.. code-block:: python + + from importlib.metadata import entry_points + display_eps = entry_points(group='timmins.display') + +.. note:: + Each ``importlib.metadata.EntryPoint`` object is an object containing a ``name``, a + ``group``, and a ``value``. For example, after setting up the plugin package as + described below, ``display_eps`` in the above code will look like this: [#package_metadata]_ + + .. code-block:: python + + ( + EntryPoint(name='excl', value='timmins_plugin_fancy:excl_display', group='timmins.display'), + ..., + ) + +``display_eps`` will now be a list of ``EntryPoint`` objects, each referring to ``display()``-like +functions defined by one or more installed plugin packages. Then, to import a specific +``display()``-like function - let us choose the one corresponding to the first discovered +entry point - we can use the ``load()`` method as follows: + +.. code-block:: python + + display = display_eps[0].load() + +Finally, a sensible behaviour would be that if we cannot find any plugin packages customizing +the ``display()`` function, we should fall back to our default implementation which prints +the text as it is. With this behaviour included, the code in ``src/timmins/__init__.py`` +finally becomes: + +.. code-block:: python + + from importlib.metadata import entry_points + display_eps = entry_points(group='timmins.display') + try: + display = display_eps[0].load() + except IndexError: + def display(text): + print(text) + + def hello_world(): + display('Hello world') + +That finishes the setup on ``timmins``'s side. Next, we need to implement a plugin +which implements the entry point ``timmins.display``. Let us name this plugin +``timmins-plugin-fancy``, and set it up with the following directory structure:: + + timmins-plugin-fancy + ├── pyproject.toml # and/or setup.cfg, setup.py + └── src + └── timmins_plugin_fancy + └── __init__.py + +And then, inside ``src/timmins_plugin_fancy/__init__.py``, we can put a function +named ``excl_display()`` that prints the given text surrounded by exclamation marks: + +.. code-block:: python + + def excl_display(text): + print('!!!', text, '!!!') + +This is the ``display()``-like function that we are looking to supply to the +``timmins`` package. We can do that by adding the following in the configuration +of ``timmins-plugin-fancy``: + +.. tab:: pyproject.toml + + .. code-block:: toml + + # Note the quotes around timmins.display in order to escape the dot . + [project.entry-points."timmins.display"] + excl = "timmins_plugin_fancy:excl_display" + +.. tab:: setup.cfg + + .. code-block:: ini + + [options.entry_points] + timmins.display = + excl = timmins_plugin_fancy:excl_display + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup + + setup( + # ..., + entry_points = { + 'timmins.display': [ + 'excl = timmins_plugin_fancy:excl_display' + ] + } + ) + +Basically, this configuration states that we are a supplying an entry point +under the group ``timmins.display``. The entry point is named ``excl`` and it +refers to the function ``excl_display`` defined by the package ``timmins-plugin-fancy``. + +Now, if we install both ``timmins`` and ``timmins-plugin-fancy``, we should get +the following: + +.. code-block:: pycon + + >>> from timmins import hello_world + >>> hello_world() + !!! Hello world !!! + +whereas if we only install ``timmins`` and not ``timmins-plugin-fancy``, we should +get the following: + +.. code-block:: pycon + + >>> from timmins import hello_world + >>> hello_world() + Hello world + +Therefore, our plugin works. + +Our plugin could have also defined multiple entry points under the group ``timmins.display``. +For example, in ``src/timmins_plugin_fancy/__init__.py`` we could have two ``display()``-like +functions, as follows: + +.. code-block:: python + + def excl_display(text): + print('!!!', text, '!!!') + + def lined_display(text): + print(''.join(['-' for _ in text])) + print(text) + print(''.join(['-' for _ in text])) + +The configuration of ``timmins-plugin-fancy`` would then change to: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.entry-points."timmins.display"] + excl = "timmins_plugin_fancy:excl_display" + lined = "timmins_plugin_fancy:lined_display" + +.. tab:: setup.cfg + + .. code-block:: ini + + [options.entry_points] + timmins.display = + excl = timmins_plugin_fancy:excl_display + lined = timmins_plugin_fancy:lined_display + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup + + setup( + # ..., + entry_points = { + 'timmins.display': [ + 'excl = timmins_plugin_fancy:excl_display', + 'lined = timmins_plugin_fancy:lined_display', + ] + } + ) + +On the ``timmins`` side, we can also use a different strategy of loading entry +points. For example, we can search for a specific display style: + +.. code-block:: python + + display_eps = entry_points(group='timmins.display') + try: + display = display_eps['lined'].load() + except KeyError: + # if the 'lined' display is not available, use something else + ... + +Or we can also load all plugins under the given group. Though this might not +be of much use in our current example, there are several scenarios in which this +is useful: + +.. code-block:: python + + display_eps = entry_points(group='timmins.display') + for ep in display_eps: + display = ep.load() + # do something with display + ... + +Another point is that in this particular example, we have used plugins to +customize the behaviour of a function (``display()``). In general, we can use entry +points to enable plugins to not only customize the behaviour of functions, but also +of entire classes and modules. This is unlike the case of console/GUI scripts, +where entry points can only refer to functions. The syntax used for specifying the +entry points remains the same as for console/GUI scripts, and is discussed in the +`last section <#entry-points-syntax>`_. + +.. tip:: + The recommended approach for loading and importing entry points is the + :mod:`importlib.metadata` module, + which is a part of the standard library since Python 3.8. For older versions of + Python, its backport :pypi:`importlib_metadata` should be used. While using the + backport, the only change that has to be made is to replace ``importlib.metadata`` + with ``importlib_metadata``, i.e. + + .. code-block:: python + + from importlib_metadata import entry_points + ... + +In summary, entry points allow a package to open its functionalities for +customization via plugins. +The package soliciting the entry points need not have any dependency +or prior knowledge about the plugins implementing the entry points, and +downstream users are able to compose functionality by pulling together +plugins implementing the entry points. + +Entry Points Syntax +=================== + +The syntax for entry points is specified as follows:: + + <name> = <package_or_module>[:<object>[.<attr>[.<nested-attr>]*]] + +Here, the square brackets ``[]`` denote optionality and the asterisk ``*`` +denotes repetition. +``name`` is the name of the script/entry point you want to create, the left hand +side of ``:`` is the package or module that contains the object you want to invoke +(think about it as something you would write in an import statement), and the right +hand side is the object you want to invoke (e.g. a function). + +To make this syntax more clear, consider the following examples: + +Package or module + If you supply:: + + <name> = <package_or_module> + + as the entry point, where ``<package_or_module>`` can contain ``.`` in the case + of sub-modules or sub-packages, then, tools in the Python ecosystem will roughly + interpret this value as: + + .. code-block:: python + + import <package_or_module> + parsed_value = <package_or_module> + +Module-level object + If you supply:: + + <name> = <package_or_module>:<object> + + where ``<object>`` does not contain any ``.``, this will be roughly interpreted + as: + + .. code-block:: python + + from <package_or_module> import <object> + parsed_value = <object> + +Nested object + If you supply:: + + <name> = <package_or_module>:<object>.<attr>.<nested_attr> + + this will be roughly interpreted as: + + .. code-block:: python + + from <package_or_module> import <object> + parsed_value = <object>.<attr>.<nested_attr> + +In the case of console/GUI scripts, this syntax can be used to specify a function, while +in the general case of entry points as used for plugins, it can be used to specify a function, +class or module. + +---- + +.. [#use_for_scripts] + Reference: https://packaging.python.org/en/latest/specifications/entry-points/#use-for-scripts + +.. [#package_metadata] + Reference: https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/#using-package-metadata diff --git a/docs/userguide/ext_modules.rst b/docs/userguide/ext_modules.rst new file mode 100644 index 00000000..9119830c --- /dev/null +++ b/docs/userguide/ext_modules.rst @@ -0,0 +1,172 @@ +========================== +Building Extension Modules +========================== + +Setuptools can build C/C++ extension modules. The keyword argument +``ext_modules`` of ``setup()`` should be a list of instances of the +:class:`setuptools.Extension` class. + + +For example, let's consider a simple project with only one extension module:: + + <project_folder> + ├── pyproject.toml + └── foo.c + +and all project metadata configuration in the ``pyproject.toml`` file: + +.. code-block:: toml + + # pyproject.toml + [build-system] + requires = ["setuptools"] + build-backend = "setuptools.build_meta" + + [project] + name = "mylib-foo" # as it would appear on PyPI + version = "0.42" + +To instruct setuptools to compile the ``foo.c`` file into the extension module +``mylib.foo``, we need to add a ``setup.py`` file similar to the following: + +.. code-block:: python + + from setuptools import Extension, setup + + setup( + ext_modules=[ + Extension( + name="mylib.foo", # as it would be imported + # may include packages/namespaces separated by `.` + + sources=["foo.c"], # all sources are compiled into a single binary file + ), + ] + ) + +.. seealso:: + You can find more information on the `Python docs about C/C++ extensions`_. + Alternatively, you might also be interested in learn about `Cython`_. + + If you plan to distribute a package that uses extensions across multiple + platforms, :pypi:`cibuildwheel` can also be helpful. + +.. important:: + All files used to compile your extension need to be available on the system + when building the package, so please make sure to include some documentation + on how developers interested in building your package from source + can obtain operating system level dependencies + (e.g. compilers and external binary libraries/artifacts). + + You will also need to make sure that all auxiliary files that are contained + inside your :term:`project` (e.g. C headers authored by you or your team) + are configured to be included in your :term:`sdist <Source Distribution (or "sdist")>`. + Please have a look on our section on :ref:`Controlling files in the distribution`. + + +Compiler and linker options +=========================== + +The command ``build_ext`` builds C/C++ extension modules. It creates +a command line for running the compiler and linker by combining +compiler and linker options from various sources: + +.. Reference: `test_customize_compiler` in distutils/tests/test_sysconfig.py + +* the ``sysconfig`` variables ``CC``, ``CXX``, ``CCSHARED``, + ``LDSHARED``, and ``CFLAGS``, +* the environment variables ``CC``, ``CPP``, + ``CXX``, ``LDSHARED`` and ``LDFLAGS``, + ``CFLAGS``, ``CPPFLAGS``, ``LDFLAGS``, +* the ``Extension`` attributes ``include_dirs``, + ``library_dirs``, ``extra_compile_args``, ``extra_link_args``, + ``runtime_library_dirs``. + +.. Ignoring AR, ARFLAGS, RANLIB here because they are used by the (obsolete?) build_clib, not build_ext. + +Specifically, if the environment variables ``CC``, ``CPP``, ``CXX``, and ``LDSHARED`` +are set, they will be used instead of the ``sysconfig`` variables of the same names. + +The compiler options appear in the command line in the following order: + +.. Reference: "compiler_so" and distutils.ccompiler.gen_preprocess_options, CCompiler.compile, UnixCCompiler._compile + +* first, the options provided by the ``sysconfig`` variable ``CFLAGS``, +* then, the options provided by the environment variables ``CFLAGS`` and ``CPPFLAGS``, +* then, the options provided by the ``sysconfig`` variable ``CCSHARED``, +* then, a ``-I`` option for each element of ``Extension.include_dirs``, +* finally, the options provided by ``Extension.extra_compile_args``. + +The linker options appear in the command line in the following order: + +.. Reference: "linker_so" and CCompiler.link + +* first, the options provided by environment variables and ``sysconfig`` variables, +* then, a ``-L`` option for each element of ``Extension.library_dirs``, +* then, a linker-specific option like ``-Wl,-rpath`` for each element of ``Extension.runtime_library_dirs``, +* finally, the options provided by ``Extension.extra_link_args``. + +The resulting command line is then processed by the compiler and linker. +According to the GCC manual sections on `directory options`_ and +`environment variables`_, the C/C++ compiler searches for files named in +``#include <file>`` directives in the following order: + +* first, in directories given by ``-I`` options (in left-to-right order), +* then, in directories given by the environment variable ``CPATH`` (in left-to-right order), +* then, in directories given by ``-isystem`` options (in left-to-right order), +* then, in directories given by the environment variable ``C_INCLUDE_PATH`` (for C) and ``CPLUS_INCLUDE_PATH`` (for C++), +* then, in standard system directories, +* finally, in directories given by ``-idirafter`` options (in left-to-right order). + +The linker searches for libraries in the following order: + +* first, in directories given by ``-L`` options (in left-to-right order), +* then, in directories given by the environment variable ``LIBRARY_PATH`` (in left-to-right order). + + +Distributing Extensions compiled with Cython +============================================ + +When your :pypi:`Cython` extension modules *are declared using the* +:class:`setuptools.Extension` *class*, ``setuptools`` will detect at build time +whether Cython is installed or not. + +If Cython is present, then ``setuptools`` will use it to build the ``.pyx`` files. +Otherwise, ``setuptools`` will try to find and compile the equivalent ``.c`` files +(instead of ``.pyx``). These files can be generated using the +`cython command line tool`_. + +You can ensure that Cython is always automatically installed into the build +environment by including it as a :ref:`build dependency <build-requires>` in +your ``pyproject.toml``: + +.. code-block:: toml + + [build-system] + requires = [..., "cython"] + +Alternatively, you can include the ``.c`` code that is pre-compiled by Cython +into your source distribution, alongside the original ``.pyx`` files (this +might save a few seconds when building from an ``sdist``). +To improve version compatibility, you probably also want to include current +``.c`` files in your :wiki:`revision control system`, and rebuild them whenever +you check changes in for the ``.pyx`` source files. +This will ensure that people tracking your project will be able to build it +without installing Cython, and that there will be no variation due to small +differences in the generate C files. +Please checkout our docs on :ref:`controlling files in the distribution` for +more information. + +---- + +Extension API Reference +======================= + +.. autoclass:: setuptools.Extension + + +.. _Python docs about C/C++ extensions: https://docs.python.org/3/extending/extending.html +.. _Cython: https://cython.readthedocs.io/en/stable/index.html +.. _directory options: https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html +.. _environment variables: https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html +.. _cython command line tool: https://cython.readthedocs.io/en/stable/src/userguide/source_files_and_compilation.html diff --git a/docs/userguide/extension.rst b/docs/userguide/extension.rst new file mode 100644 index 00000000..6f8cbbb2 --- /dev/null +++ b/docs/userguide/extension.rst @@ -0,0 +1,308 @@ +.. _Creating ``distutils`` Extensions: + +Extending or Customizing Setuptools +=================================== + +Setuptools design is based on the distutils_ package originally distributed +as part of Python's standard library, effectively serving as its successor +(as established in :pep:`632`). + +This means that ``setuptools`` strives to honor the extension mechanisms +provided by ``distutils``, and allows developers to create third party packages +that modify or augment the build process behavior. + +A simple way of doing that is to hook in new or existing +commands and ``setup()`` arguments just by defining "entry points". These +are mappings from command or argument names to a specification of where to +import a handler from. (See the section on :ref:`Dynamic Discovery of +Services and Plugins` for some more background on entry points). + +The following sections describe the most common procedures for extending +the ``distutils`` functionality used by ``setuptools``. + +.. important:: + Any entry-point defined in your ``setup.cfg``, ``setup.py`` or + ``pyproject.toml`` files are not immediately available for use. Your + package needs to be installed first, then ``setuptools`` will be able to + access these entry points. For example consider a ``Project-A`` that + defines entry points. When building ``Project-A``, these will not be + available. If ``Project-B`` declares a :doc:`build system requirement + </userguide/dependency_management>` on ``Project-A``, then ``setuptools`` + will be able to use ``Project-A``' customizations. + +Customizing Commands +-------------------- + +Both ``setuptools`` and ``distutils`` are structured around the *command design +pattern*. This means that each main action executed when building a +distribution package (such as creating a :term:`sdist <Source Distribution (or "sdist")>` +or :term:`wheel`) correspond to the implementation of a Python class. + +Originally in ``distutils``, these commands would correspond to actual CLI +arguments that could be passed to the ``setup.py`` script to trigger a +different aspect of the build. In ``setuptools``, however, these command +objects are just a design abstraction that encapsulate logic and help to +organise the code. + +You can overwrite exiting commands (or add new ones) by defining entry +points in the ``distutils.commands`` group. For example, if you wanted to add +a ``foo`` command, you might add something like this to your project: + +.. code-block:: ini + + # setup.cfg + ... + [options.entry_points] + distutils.commands = + foo = mypackage.some_module:foo + +Assuming, of course, that the ``foo`` class in ``mypackage.some_module`` is +a ``setuptools.Command`` subclass (documented below). + +Once a project containing such entry points has been activated on ``sys.path``, +(e.g. by running ``pip install``) the command(s) will be available to any +``setuptools``-based project. In fact, this is +how setuptools' own commands are installed: the setuptools project's setup +script defines entry points for them! + +The commands ``sdist``, ``build_py`` and ``build_ext`` are especially useful +to customize ``setuptools`` builds. Note however that when overwriting existing +commands, you should be very careful to maintain API compatibility. +Custom commands should try to replicate the same overall behavior as the +original classes, and when possible, even inherit from them. + +You should also consider handling exceptions such as ``CompileError``, +``LinkError``, ``LibError``, among others. These exceptions are available in +the ``setuptools.errors`` module. + +.. autoclass:: setuptools.Command + :members: + + +Supporting sdists and editable installs in ``build`` sub-commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``build`` sub-commands (like ``build_py`` and ``build_ext``) +are encouraged to implement the following protocol: + +.. autoclass:: setuptools.command.build.SubCommand + :members: + + +Adding Arguments +---------------- + +.. warning:: Adding arguments to setup is discouraged as such arguments + are only supported through imperative execution and not supported through + declarative config. + +Sometimes, your commands may need additional arguments to the ``setup()`` +call. You can enable this by defining entry points in the +``distutils.setup_keywords`` group. For example, if you wanted a ``setup()`` +argument called ``bar_baz``, you might add something like this to your +extension project: + +.. code-block:: ini + + # setup.cfg + ... + [options.entry_points] + distutils.commands = + foo = mypackage.some_module:foo + distutils.setup_keywords = + bar_baz = mypackage.some_module:validate_bar_baz + +The idea here is that the entry point defines a function that will be called +to validate the ``setup()`` argument, if it's supplied. The ``Distribution`` +object will have the initial value of the attribute set to ``None``, and the +validation function will only be called if the ``setup()`` call sets it to +a non-``None`` value. Here's an example validation function:: + + def assert_bool(dist, attr, value): + """Verify that value is True, False, 0, or 1""" + if bool(value) != value: + raise SetupError( + "%r must be a boolean value (got %r)" % (attr,value) + ) + +Your function should accept three arguments: the ``Distribution`` object, +the attribute name, and the attribute value. It should raise a +``SetupError`` (from the ``setuptools.errors`` module) if the argument +is invalid. Remember, your function will only be called with non-``None`` values, +and the default value of arguments defined this way is always ``None``. So, your +commands should always be prepared for the possibility that the attribute will +be ``None`` when they access it later. + +If more than one active distribution defines an entry point for the same +``setup()`` argument, *all* of them will be called. This allows multiple +extensions to define a common argument, as long as they agree on +what values of that argument are valid. + + +Customizing Distribution Options +-------------------------------- + +Plugins may wish to extend or alter the options on a ``Distribution`` object to +suit the purposes of that project. For example, a tool that infers the +``Distribution.version`` from SCM-metadata may need to hook into the +option finalization. To enable this feature, Setuptools offers an entry +point ``setuptools.finalize_distribution_options``. That entry point must +be a callable taking one argument (the ``Distribution`` instance). + +If the callable has an ``.order`` property, that value will be used to +determine the order in which the hook is called. Lower numbers are called +first and the default is zero (0). + +Plugins may read, alter, and set properties on the distribution, but each +plugin is encouraged to load the configuration/settings for their behavior +independently. + + +Defining Additional Metadata +---------------------------- + +Some extensible applications and frameworks may need to define their own kinds +of metadata, which they can then access using the :mod:`importlib.metadata` APIs. +Ordinarily, this is done by having plugin +developers include additional files in their ``ProjectName.egg-info`` +directory. However, since it can be tedious to create such files by hand, you +may want to create an extension that will create the necessary files +from arguments to ``setup()``, in much the same way that ``setuptools`` does +for many of the ``setup()`` arguments it adds. See the section below for more +details. + + +.. _Adding new EGG-INFO Files: + +Adding new EGG-INFO Files +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some extensible applications or frameworks may want to allow third parties to +develop plugins with application or framework-specific metadata included in +the plugins' EGG-INFO directory, for easy access via the ``pkg_resources`` +metadata API. The easiest way to allow this is to create an extension +to be used from the plugin projects' setup scripts (via ``setup_requires``) +that defines a new setup keyword, and then uses that data to write an EGG-INFO +file when the ``egg_info`` command is run. + +The ``egg_info`` command looks for extension points in an ``egg_info.writers`` +group, and calls them to write the files. Here's a simple example of an +extension defining a setup argument ``foo_bar``, which is a list of +lines that will be written to ``foo_bar.txt`` in the EGG-INFO directory of any +project that uses the argument: + +.. code-block:: ini + + # setup.cfg + ... + [options.entry_points] + distutils.setup_keywords = + foo_bar = setuptools.dist:assert_string_list + egg_info.writers = + foo_bar.txt = setuptools.command.egg_info:write_arg + +This simple example makes use of two utility functions defined by setuptools +for its own use: a routine to validate that a setup keyword is a sequence of +strings, and another one that looks up a setup argument and writes it to +a file. Here's what the writer utility looks like:: + + def write_arg(cmd, basename, filename): + argname = os.path.splitext(basename)[0] + value = getattr(cmd.distribution, argname, None) + if value is not None: + value = "\n".join(value) + "\n" + cmd.write_or_delete_file(argname, filename, value) + +As you can see, ``egg_info.writers`` entry points must be a function taking +three arguments: a ``egg_info`` command instance, the basename of the file to +write (e.g. ``foo_bar.txt``), and the actual full filename that should be +written to. + +In general, writer functions should honor the command object's ``dry_run`` +setting when writing files, and use ``logging`` to do any console output. +The easiest way to conform to this requirement is to use +the ``cmd`` object's ``write_file()``, ``delete_file()``, and +``write_or_delete_file()`` methods exclusively for your file operations. +See those methods' docstrings for more details. + + +.. _Adding Support for Revision Control Systems: + +Adding Support for Revision Control Systems +------------------------------------------------- + +If the files you want to include in the source distribution are tracked using +Git, Mercurial or SVN, you can use the following packages to achieve that: + +- Git and Mercurial: :pypi:`setuptools_scm` +- SVN: :pypi:`setuptools_svn` + +If you would like to create a plugin for ``setuptools`` to find files tracked +by another revision control system, you can do so by adding an entry point to +the ``setuptools.file_finders`` group. The entry point should be a function +accepting a single directory name, and should yield all the filenames within +that directory (and any subdirectories thereof) that are under revision +control. + +For example, if you were going to create a plugin for a revision control system +called "foobar", you would write a function something like this: + +.. code-block:: python + + def find_files_for_foobar(dirname): + ... # loop to yield paths that start with `dirname` + +And you would register it in a setup script using something like this: + +.. code-block:: ini + + # setup.cfg + ... + + [options.entry_points] + setuptools.file_finders = + foobar = my_foobar_module:find_files_for_foobar + +Then, anyone who wants to use your plugin can simply install it, and their +local setuptools installation will be able to find the necessary files. + +It is not necessary to distribute source control plugins with projects that +simply use the other source control system, or to specify the plugins in +``setup_requires``. When you create a source distribution with the ``sdist`` +command, setuptools automatically records what files were found in the +``SOURCES.txt`` file. That way, recipients of source distributions don't need +to have revision control at all. However, if someone is working on a package +by checking out with that system, they will need the same plugin(s) that the +original author is using. + +A few important points for writing revision control file finders: + +* Your finder function MUST return relative paths, created by appending to the + passed-in directory name. Absolute paths are NOT allowed, nor are relative + paths that reference a parent directory of the passed-in directory. + +* Your finder function MUST accept an empty string as the directory name, + meaning the current directory. You MUST NOT convert this to a dot; just + yield relative paths. So, yielding a subdirectory named ``some/dir`` under + the current directory should NOT be rendered as ``./some/dir`` or + ``/somewhere/some/dir``, but *always* as simply ``some/dir`` + +* Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully + with the absence of needed programs (i.e., ones belonging to the revision + control system itself. It *may*, however, use ``logging.warning()`` to + inform the user of the missing program(s). + + +.. _distutils: https://docs.python.org/3.9/library/distutils.html + + +Final Remarks +------------- + +* To use a ``setuptools`` plugin, your users will need to add your package as a + build requirement to their build-system configuration. Please check out our + guides on :doc:`/userguide/dependency_management` for more information. + +* Directly calling ``python setup.py ...`` is considered a **deprecated** practice. + You should not add new commands to ``setuptools`` expecting them to be run + via this interface. diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst new file mode 100644 index 00000000..d631c5d8 --- /dev/null +++ b/docs/userguide/index.rst @@ -0,0 +1,48 @@ +================================================== +Building and Distributing Packages with Setuptools +================================================== + +The first step towards sharing a Python library or program is to build a +distribution package [#package-overload]_. This includes adding a set of +additional files containing metadata and configuration to not only instruct +``setuptools`` on how the distribution should be built but also +to help installer (such as :pypi:`pip`) during the installation process. + +This document contains information to help Python developers through this +process. Please check the :doc:`/userguide/quickstart` for an overview of +the workflow. + +Also note that ``setuptools`` is what is known in the community as :pep:`build +backend <517#terminology-and-goals>`, user facing interfaces are provided by tools +such as :pypi:`pip` and :pypi:`build`. To use ``setuptools``, one must +explicitly create a ``pyproject.toml`` file as described :doc:`/build_meta`. + + +Contents +======== + +.. toctree:: + :maxdepth: 1 + + quickstart + package_discovery + dependency_management + development_mode + entry_point + datafiles + ext_modules + distribution + miscellaneous + extension + declarative_config + pyproject_config + +--- + +.. rubric:: Notes + +.. [#package-overload] + A :term:`Distribution Package` is also referred in the Python community simply as "package" + Unfortunately, this jargon might be a bit confusing for new users because the term package + can also to refer any :term:`directory <package>` (or sub directory) used to organize + :term:`modules <module>` and auxiliary files. diff --git a/docs/userguide/miscellaneous.rst b/docs/userguide/miscellaneous.rst new file mode 100644 index 00000000..19908e05 --- /dev/null +++ b/docs/userguide/miscellaneous.rst @@ -0,0 +1,100 @@ +.. _Controlling files in the distribution: + +Controlling files in the distribution +===================================== + +For the most common use cases, ``setuptools`` will automatically find out which +files are necessary for distributing the package. +These include all :term:`pure Python modules <Pure Module>` in the +``py_modules`` or ``packages`` configuration, and the C sources (but not C +headers) listed as part of extensions when creating a :term:`source +distribution (or "sdist")`. + +However, when building more complex packages (e.g. packages that include +non-Python files, or that need to use custom C headers), you might find that +not all files present in your project folder are included in package +:term:`distribution archive <Distribution Package>`. + +If you are using a :wiki:`Revision Control System`, such as git_ or mercurial_, +and your source distributions only need to include files that you're +tracking in revision control, you can use a ``setuptools`` :ref:`plugin <Adding +Support for Revision Control Systems>`, such as :pypi:`setuptools-scm` or +:pypi:`setuptools-svn` to automatically include all tracked files into the ``sdist``. + +.. _Using MANIFEST.in: + +Alternatively, if you need finer control over the files (e.g. you don't want to +distribute :wiki:`CI/CD`-related files) or you need automatically generated files, +you can add a ``MANIFEST.in`` file at the root of your project, +to specify any files that the default file location algorithm doesn't catch. + +This file contains instructions that tell ``setuptools`` which files exactly +should be part of the ``sdist`` (or not). +A comprehensive guide to ``MANIFEST.in`` syntax is available at the +:doc:`PyPA's Packaging User Guide <PyPUG:guides/using-manifest-in>`. + +.. attention:: + Please note that ``setuptools`` supports the ``MANIFEST.in``, + and not ``MANIFEST`` (no extension). Any documentation, tutorial or example + that recommends using ``MANIFEST`` (no extension) is likely outdated. + +.. tip:: + The ``MANIFEST.in`` file contains commands that allow you to discover and + manipulate lists of files. There are many commands that can be used with + different objectives, but you should try to not make your ``MANIFEST.in`` + file too fine grained. + + A good idea is to start with a ``graft`` command (to add all + files inside a set of directories) and then fine tune the file selection + by removing the excess or adding isolated files. + +An example of ``MANIFEST.in`` for a simple project that organized according to a +:ref:`src-layout` is: + +.. code-block:: bash + + # MANIFEST.in -- just for illustration + graft src + graft tests + graft docs + # `-> adds all files inside a directory + + include tox.ini + # `-> matches file paths relative to the root of the project + + global-exclude *~ *.py[cod] *.so + # `-> matches file names (regardless of directory) + +Once the correct files are present in the ``sdist``, they can then be used by +binary extensions during the build process, or included in the final +:term:`wheel <Wheel>` [#build-process]_ if you configure ``setuptools`` with +``include_package_data=True``. + +.. important:: + Please note that, when using ``include_package_data=True``, only files **inside + the package directory** are included in the final ``wheel``, by default. + + So for example, if you create a :term:`Python project <Project>` that uses + :pypi:`setuptools-scm` and have a ``tests`` directory outside of the package + folder, the ``tests`` directory will be present in the ``sdist`` but not in the + ``wheel`` [#wheel-vs-sdist]_. + + See :doc:`/userguide/datafiles` for more information. + +---- + +.. [#build-process] + You can think about the build process as two stages: first the ``sdist`` + will be created and then the ``wheel`` will be produced from that ``sdist``. + +.. [#wheel-vs-sdist] + This happens because the ``sdist`` can contain files that are useful during + development or the build process itself, but not in runtime (e.g. tests, + docs, examples, etc...). + The ``wheel``, on the other hand, is a file format that has been optimized + and is ready to be unpacked into a running installation of Python or + :term:`Virtual Environment`. + Therefore it only contains items that are required during runtime. + +.. _git: https://git-scm.com +.. _mercurial: https://www.mercurial-scm.org diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst new file mode 100644 index 00000000..7dda84a8 --- /dev/null +++ b/docs/userguide/package_discovery.rst @@ -0,0 +1,589 @@ +.. _`package_discovery`: + +======================================== +Package Discovery and Namespace Packages +======================================== + +.. note:: + a full specification for the keywords supplied to ``setup.cfg`` or + ``setup.py`` can be found at :doc:`keywords reference </references/keywords>` + +.. important:: + The examples provided here are only to demonstrate the functionality + introduced. More metadata and options arguments need to be supplied + if you want to replicate them on your system. If you are completely + new to setuptools, the :doc:`quickstart` section is a good place to start. + +``Setuptools`` provides powerful tools to handle package discovery, including +support for namespace packages. + +Normally, you would specify the packages to be included manually in the following manner: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + #... + packages = + mypkg + mypkg.subpkg1 + mypkg.subpkg2 + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2'] + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + # ... + [tool.setuptools] + packages = ["mypkg", "mypkg.subpkg1", "mypkg.subpkg2"] + # ... + + +If your packages are not in the root of the repository or do not correspond +exactly to the directory structure, you also need to configure ``package_dir``: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + # ... + package_dir = + = src + # directory containing all the packages (e.g. src/mypkg, src/mypkg/subpkg1, ...) + # OR + package_dir = + mypkg = lib + # mypkg.module corresponds to lib/module.py + mypkg.subpkg1 = lib1 + # mypkg.subpkg1.module1 corresponds to lib1/module1.py + mypkg.subpkg2 = lib2 + # mypkg.subpkg2.module2 corresponds to lib2/module2.py + # ... + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + package_dir = {"": "src"} + # directory containing all the packages (e.g. src/mypkg, src/mypkg/subpkg1, ...) + ) + + # OR + + setup( + # ... + package_dir = { + "mypkg": "lib", # mypkg.module corresponds to lib/mod.py + "mypkg.subpkg1": "lib1", # mypkg.subpkg1.module1 corresponds to lib1/module1.py + "mypkg.subpkg2": "lib2" # mypkg.subpkg2.module2 corresponds to lib2/module2.py + # ... + ) + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools] + # ... + package-dir = {"" = "src"} + # directory containing all the packages (e.g. src/mypkg1, src/mypkg2) + + # OR + + [tool.setuptools.package-dir] + mypkg = "lib" + # mypkg.module corresponds to lib/module.py + "mypkg.subpkg1" = "lib1" + # mypkg.subpkg1.module1 corresponds to lib1/module1.py + "mypkg.subpkg2" = "lib2" + # mypkg.subpkg2.module2 corresponds to lib2/module2.py + # ... + +This can get tiresome really quickly. To speed things up, you can rely on +setuptools automatic discovery, or use the provided tools, as explained in +the following sections. + +.. important:: + Although ``setuptools`` allows developers to create a very complex mapping + between directory names and package names, it is better to *keep it simple* + and reflect the desired package hierarchy in the directory structure, + preserving the same names. + +.. _auto-discovery: + +Automatic discovery +=================== + +.. warning:: Automatic discovery is a **beta** feature and might change in the future. + See :ref:`custom-discovery` for other methods of discovery. + +By default ``setuptools`` will consider 2 popular project layouts, each one with +its own set of advantages and disadvantages [#layout1]_ [#layout2]_ as +discussed in the following sections. + +Setuptools will automatically scan your project directory looking for these +layouts and try to guess the correct values for the :ref:`packages <declarative +config>` and :doc:`py_modules </references/keywords>` configuration. + +.. important:: + Automatic discovery will **only** be enabled if you **don't** provide any + configuration for ``packages`` and ``py_modules``. + If at least one of them is explicitly set, automatic discovery will not take place. + + **Note**: specifying ``ext_modules`` might also prevent auto-discover from + taking place, unless your opt into :doc:`pyproject_config` (which will + disable the backward compatible behaviour). + +.. _src-layout: + +src-layout +---------- +The project should contain a ``src`` directory under the project root and +all modules and packages meant for distribution are placed inside this +directory:: + + project_root_directory + ├── pyproject.toml # AND/OR setup.cfg, setup.py + ├── ... + └── src/ + └── mypkg/ + ├── __init__.py + ├── ... + ├── module.py + ├── subpkg1/ + │ ├── __init__.py + │ ├── ... + │ └── module1.py + └── subpkg2/ + ├── __init__.py + ├── ... + └── module2.py + +This layout is very handy when you wish to use automatic discovery, +since you don't have to worry about other Python files or folders in your +project root being distributed by mistake. In some circumstances it can be +also less error-prone for testing or when using :pep:`420`-style packages. +On the other hand you cannot rely on the implicit ``PYTHONPATH=.`` to fire +up the Python REPL and play with your package (you will need an +`editable install`_ to be able to do that). + +.. _flat-layout: + +flat-layout +----------- +*(also known as "adhoc")* + +The package folder(s) are placed directly under the project root:: + + project_root_directory + ├── pyproject.toml # AND/OR setup.cfg, setup.py + ├── ... + └── mypkg/ + ├── __init__.py + ├── ... + ├── module.py + ├── subpkg1/ + │ ├── __init__.py + │ ├── ... + │ └── module1.py + └── subpkg2/ + ├── __init__.py + ├── ... + └── module2.py + +This layout is very practical for using the REPL, but in some situations +it can be more error-prone (e.g. during tests or if you have a bunch +of folders or Python files hanging around your project root). + +To avoid confusion, file and folder names that are used by popular tools (or +that correspond to well-known conventions, such as distributing documentation +alongside the project code) are automatically filtered out in the case of +*flat-layout*: + +.. autoattribute:: setuptools.discovery.FlatLayoutPackageFinder.DEFAULT_EXCLUDE + +.. autoattribute:: setuptools.discovery.FlatLayoutModuleFinder.DEFAULT_EXCLUDE + +.. warning:: + If you are using auto-discovery with *flat-layout*, ``setuptools`` will + refuse to create :term:`distribution archives <Distribution Package>` with + multiple top-level packages or modules. + + This is done to prevent common errors such as accidentally publishing code + not meant for distribution (e.g. maintenance-related scripts). + + Users that purposefully want to create multi-package distributions are + advised to use :ref:`custom-discovery` or the ``src-layout``. + +There is also a handy variation of the *flat-layout* for utilities/libraries +that can be implemented with a single Python file: + +single-module distribution +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A standalone module is placed directly under the project root, instead of +inside a package folder:: + + project_root_directory + ├── pyproject.toml # AND/OR setup.cfg, setup.py + ├── ... + └── single_file_lib.py + + +.. _custom-discovery: + +Custom discovery +================ + +If the automatic discovery does not work for you +(e.g., you want to *include* in the distribution top-level packages with +reserved names such as ``tasks``, ``example`` or ``docs``, or you want to +*exclude* nested packages that would be otherwise included), you can use +the provided tools for package discovery: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + packages = find: + #or + packages = find_namespace: + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import find_packages + # or + from setuptools import find_namespace_packages + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + # ... + [tool.setuptools.packages] + find = {} # Scanning implicit namespaces is active by default + # OR + find = {namespaces = false} # Disable implicit namespaces + + +Finding simple packages +----------------------- +Let's start with the first tool. ``find:`` (``find_packages()``) takes a source +directory and two lists of package name patterns to exclude and include, and +then returns a list of ``str`` representing the packages it could find. To use +it, consider the following directory:: + + mypkg + ├── pyproject.toml # AND/OR setup.cfg, setup.py + └── src + ├── pkg1 + │ └── __init__.py + ├── pkg2 + │ └── __init__.py + ├── additional + │ └── __init__.py + └── pkg + └── namespace + └── __init__.py + +To have setuptools to automatically include packages found +in ``src`` that start with the name ``pkg`` and not ``additional``: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + packages = find: + package_dir = + =src + + [options.packages.find] + where = src + include = pkg* + # alternatively: `exclude = additional*` + + .. note:: + ``pkg`` does not contain an ``__init__.py`` file, therefore + ``pkg.namespace`` is ignored by ``find:`` (see ``find_namespace:`` below). + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + packages=find_packages( + where='src', + include=['pkg*'], # alternatively: `exclude=['additional*']` + ), + package_dir={"": "src"} + # ... + ) + + + .. note:: + ``pkg`` does not contain an ``__init__.py`` file, therefore + ``pkg.namespace`` is ignored by ``find_packages()`` + (see ``find_namespace_packages()`` below). + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] + include = ["pkg*"] # alternatively: `exclude = ["additional*"]` + namespaces = false + + .. note:: + When using ``tool.setuptools.packages.find`` in ``pyproject.toml``, + setuptools will consider :pep:`implicit namespaces <420>` by default when + scanning your project directory. + To avoid ``pkg.namespace`` from being added to your package list + you can set ``namespaces = false``. This will prevent any folder + without an ``__init__.py`` file from being scanned. + +.. important:: + ``include`` and ``exclude`` accept strings representing :mod:`glob` patterns. + These patterns should match the **full** name of the Python module (as if it + was written in an ``import`` statement). + + For example if you have ``util`` pattern, it will match + ``util/__init__.py`` but not ``util/files/__init__.py``. + + The fact that the parent package is matched by the pattern will not dictate + if the submodule will be included or excluded from the distribution. + You will need to explicitly add a wildcard (e.g. ``util*``) + if you want the pattern to also match submodules. + +.. _Namespace Packages: + +Finding namespace packages +-------------------------- +``setuptools`` provides ``find_namespace:`` (``find_namespace_packages()``) +which behaves similarly to ``find:`` but works with namespace packages. + +Before diving in, it is important to have a good understanding of what +:pep:`namespace packages <420>` are. Here is a quick recap. + +When you have two packages organized as follows: + +.. code-block:: bash + + /Users/Desktop/timmins/foo/__init__.py + /Library/timmins/bar/__init__.py + +If both ``Desktop`` and ``Library`` are on your ``PYTHONPATH``, then a +namespace package called ``timmins`` will be created automatically for you when +you invoke the import mechanism, allowing you to accomplish the following: + +.. code-block:: pycon + + >>> import timmins.foo + >>> import timmins.bar + +as if there is only one ``timmins`` on your system. The two packages can then +be distributed separately and installed individually without affecting the +other one. + +Now, suppose you decide to package the ``foo`` part for distribution and start +by creating a project directory organized as follows:: + + foo + ├── pyproject.toml # AND/OR setup.cfg, setup.py + └── src + └── timmins + └── foo + └── __init__.py + +If you want the ``timmins.foo`` to be automatically included in the +distribution, then you will need to specify: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + package_dir = + =src + packages = find_namespace: + + [options.packages.find] + where = src + + ``find:`` won't work because ``timmins`` doesn't contain ``__init__.py`` + directly, instead, you have to use ``find_namespace:``. + + You can think of ``find_namespace:`` as identical to ``find:`` except it + would count a directory as a package even if it doesn't contain ``__init__.py`` + file directly. + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + packages=find_namespace_packages(where='src'), + package_dir={"": "src"} + # ... + ) + + When you use ``find_packages()``, all directories without an + ``__init__.py`` file will be disconsidered. + On the other hand, ``find_namespace_packages()`` will scan all + directories. + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] + + When using ``tool.setuptools.packages.find`` in ``pyproject.toml``, + setuptools will consider :pep:`implicit namespaces <420>` by default when + scanning your project directory. + +After installing the package distribution, ``timmins.foo`` would become +available to your interpreter. + +.. warning:: + Please have in mind that ``find_namespace:`` (setup.cfg), + ``find_namespace_packages()`` (setup.py) and ``find`` (pyproject.toml) will + scan **all** folders that you have in your project directory if you use a + :ref:`flat-layout`. + + If used naïvely, this might result in unwanted files being added to your + final wheel. For example, with a project directory organized as follows:: + + foo + ├── docs + │ └── conf.py + ├── timmins + │ └── foo + │ └── __init__.py + └── tests + └── tests_foo + └── __init__.py + + final users will end up installing not only ``timmins.foo``, but also + ``docs`` and ``tests.tests_foo``. + + A simple way to fix this is to adopt the aforementioned :ref:`src-layout`, + or make sure to properly configure the ``include`` and/or ``exclude`` + accordingly. + +.. tip:: + After :ref:`building your package <building>`, you can have a look if all + the files are correct (nothing missing or extra), by running the following + commands: + + .. code-block:: bash + + tar tf dist/*.tar.gz + unzip -l dist/*.whl + + This requires the ``tar`` and ``unzip`` to be installed in your OS. + On Windows you can also use a GUI program such as 7zip_. + + +Legacy Namespace Packages +========================= +The fact you can create namespace packages so effortlessly above is credited +to `PEP 420 <https://www.python.org/dev/peps/pep-0420/>`_. It used to be more +cumbersome to accomplish the same result. Historically, there were two methods +to create namespace packages. One is the ``pkg_resources`` style supported by +``setuptools`` and the other one being ``pkgutils`` style offered by +``pkgutils`` module in Python. Both are now considered *deprecated* despite the +fact they still linger in many existing packages. These two differ in many +subtle yet significant aspects and you can find out more on `Python packaging +user guide <https://packaging.python.org/guides/packaging-namespace-packages/>`_. + + +``pkg_resource`` style namespace package +---------------------------------------- +This is the method ``setuptools`` directly supports. Starting with the same +layout, there are two pieces you need to add to it. First, an ``__init__.py`` +file directly under your namespace package directory that contains the +following: + +.. code-block:: python + + __import__("pkg_resources").declare_namespace(__name__) + +And the ``namespace_packages`` keyword in your ``setup.cfg`` or ``setup.py``: + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + namespace_packages = timmins + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + namespace_packages=['timmins'] + ) + +And your directory should look like this + +.. code-block:: bash + + foo + ├── pyproject.toml # AND/OR setup.cfg, setup.py + └── src + └── timmins + ├── __init__.py + └── foo + └── __init__.py + +Repeat the same for other packages and you can achieve the same result as +the previous section. + +``pkgutil`` style namespace package +----------------------------------- +This method is almost identical to the ``pkg_resource`` except that the +``namespace_packages`` declaration is omitted and the ``__init__.py`` +file contains the following: + +.. code-block:: python + + __path__ = __import__('pkgutil').extend_path(__path__, __name__) + +The project layout remains the same and ``pyproject.toml/setup.cfg`` remains the same. + + +---- + + +.. [#beta] + Support for adding build configuration options via the ``[tool.setuptools]`` + table in the ``pyproject.toml`` file is still in **beta** stage. + See :doc:`/userguide/pyproject_config`. +.. [#layout1] https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure +.. [#layout2] https://blog.ionelmc.ro/2017/09/25/rehashing-the-src-layout/ + +.. _editable install: https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs +.. _7zip: https://www.7-zip.org diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst new file mode 100644 index 00000000..cc811ed7 --- /dev/null +++ b/docs/userguide/pyproject_config.rst @@ -0,0 +1,248 @@ +.. _pyproject.toml config: + +----------------------------------------------------- +Configuring setuptools using ``pyproject.toml`` files +----------------------------------------------------- + +.. note:: New in 61.0.0 + +.. important:: + If compatibility with legacy builds or versions of tools that don't support + certain packaging standards (e.g. :pep:`517` or :pep:`660`), a simple ``setup.py`` + script can be added to your project [#setupcfg-caveats]_ + (while keeping the configuration in ``pyproject.toml``): + + .. code-block:: python + + from setuptools import setup + + setup() + +Starting with :pep:`621`, the Python community selected ``pyproject.toml`` as +a standard way of specifying *project metadata*. +``Setuptools`` has adopted this standard and will use the information contained +in this file as an input in the build process. + +The example below illustrates how to write a ``pyproject.toml`` file that can +be used with ``setuptools``. It contains two TOML tables (identified by the +``[table-header]`` syntax): ``build-system`` and ``project``. +The ``build-system`` table is used to tell the build frontend (e.g. +:pypi:`build` or :pypi:`pip`) to use ``setuptools`` and any other plugins (e.g. +``setuptools-scm``) to build the package. +The ``project`` table contains metadata fields as described by +:doc:`PyPUG:specifications/declaring-project-metadata` guide. + +.. _example-pyproject-config: + +.. code-block:: toml + + [build-system] + requires = ["setuptools", "setuptools-scm"] + build-backend = "setuptools.build_meta" + + [project] + name = "my_package" + description = "My package description" + readme = "README.rst" + requires-python = ">=3.7" + keywords = ["one", "two"] + license = {text = "BSD 3-Clause License"} + classifiers = [ + "Framework :: Django", + "Programming Language :: Python :: 3", + ] + dependencies = [ + "requests", + 'importlib-metadata; python_version<"3.8"', + ] + dynamic = ["version"] + + [project.optional-dependencies] + pdf = ["ReportLab>=1.2", "RXP"] + rest = ["docutils>=0.3", "pack ==1.1, ==1.3"] + + [project.scripts] + my-script = "my_package.module:function" + + # ... other project metadata fields as specified in: + # https://packaging.python.org/en/latest/specifications/declaring-project-metadata/ + +.. _setuptools-table: + +Setuptools-specific configuration +================================= + +.. warning:: + Support for declaring configurations not standardized by :pep:`621` + (i.e. the ``[tool.setuptools]`` table), + is still in **beta** stage and might change in future releases. + +While the standard ``project`` table in the ``pyproject.toml`` file covers most +of the metadata used during the packaging process, there are still some +``setuptools``-specific configurations that can be set by users that require +customization. +These configurations are completely optional and probably can be skipped when +creating simple packages. +They are equivalent to the :doc:`/references/keywords` used by the ``setup.py`` +file, and can be set via the ``tool.setuptools`` table: + +========================= =========================== ========================= +Key Value Type (TOML) Notes +========================= =========================== ========================= +``platforms`` array +``zip-safe`` boolean If not specified, ``setuptools`` will try to guess + a reasonable default for the package +``eager-resources`` array +``py-modules`` array See tip below +``packages`` array or ``find`` directive See tip below +``package-dir`` table/inline-table Used when explicitly listing ``packages`` +``namespace-packages`` array **Deprecated** - Use implicit namespaces instead (:pep:`420`) +``package-data`` table/inline-table See :doc:`/userguide/datafiles` +``include-package-data`` boolean ``True`` by default +``exclude-package-data`` table/inline-table +``license-files`` array of glob patterns **Provisional** - likely to change with :pep:`639` + (by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``) +``data-files`` table/inline-table **Discouraged** - check :doc:`/userguide/datafiles` +``script-files`` array **Deprecated** - equivalent to the ``script`` keyword in ``setup.py`` + (should be avoided in favour of ``project.scripts``) +``provides`` array **Ignored by pip** +``obsoletes`` array **Ignored by pip** +========================= =========================== ========================= + +.. note:: + The `TOML value types`_ ``array`` and ``table/inline-table`` are roughly + equivalent to the Python's :obj:`list` and :obj:`dict` data types, respectively. + +Please note that some of these configurations are deprecated or at least +discouraged, but they are made available to ensure portability. +New packages should avoid relying on deprecated/discouraged fields, and +existing packages should consider alternatives. + +.. tip:: + When both ``py-modules`` and ``packages`` are left unspecified, + ``setuptools`` will attempt to perform :ref:`auto-discovery`, which should + cover most popular project directory organization techniques, such as the + :ref:`src-layout` and the :ref:`flat-layout`. + + However if your project does not follow these conventional layouts + (e.g. you want to use a ``flat-layout`` but at the same time have custom + directories at the root of your project), you might need to use the ``find`` + directive [#directives]_ as shown below: + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] # list of folders that contain the packages (["."] by default) + include = ["my_package*"] # package names should match these glob patterns (["*"] by default) + exclude = ["my_package.tests*"] # exclude packages matching these glob patterns (empty by default) + namespaces = false # to disable scanning PEP 420 namespaces (true by default) + + Note that the glob patterns in the example above need to be matched + by the **entire** package name. This means that if you specify ``exclude = ["tests"]``, + modules like ``tests.my_package.test1`` will still be included in the distribution + (to remove them, add a wildcard to the end of the pattern: ``"tests*"``). + + Alternatively, you can explicitly list the packages in modules: + + .. code-block:: toml + + [tool.setuptools] + packages = ["my_package"] + + +.. _dynamic-pyproject-config: + +Dynamic Metadata +================ + +Note that in the first example of this page we use ``dynamic`` to identify +which metadata fields are dynamically computed during the build by either +``setuptools`` itself or the plugins installed via ``build-system.requires`` +(e.g. ``setuptools-scm`` is capable of deriving the current project version +directly from the ``git`` :wiki:`version control` system). + +Currently the following fields can be listed as dynamic: ``version``, +``classifiers``, ``description``, ``entry-points``, ``scripts``, +``gui-scripts`` and ``readme``. +When these fields are expected to be provided by ``setuptools`` a +corresponding entry is required in the ``tool.setuptools.dynamic`` table +[#entry-points]_. For example: + +.. code-block:: toml + + # ... + [project] + name = "my_package" + dynamic = ["version", "readme"] + # ... + [tool.setuptools.dynamic] + version = {attr = "my_package.VERSION"} + readme = {file = ["README.rst", "USAGE.rst"]} + +In the ``dynamic`` table, the ``attr`` directive [#directives]_ will read an +attribute from the given module [#attr]_, while ``file`` will read the contents +of all given files and concatenate them in a single string. + +========================== =================== ================================================================================================= +Key Directive Notes +========================== =================== ================================================================================================= +``version`` ``attr``, ``file`` +``readme`` ``file`` +``description`` ``file`` One-line text +``classifiers`` ``file`` Multi-line text with one classifier per line +``entry-points`` ``file`` INI format following :doc:`PyPUG:specifications/entry-points` + (``console_scripts`` and ``gui_scripts`` can be included) +``dependencies`` ``file`` ``requirements.txt`` format (``#`` comments and blank lines excluded) **BETA** +``optional-dependencies`` ``file`` ``requirements.txt`` format per group (``#`` comments and blank lines excluded) **BETA** +========================== =================== ================================================================================================= + +Supporting ``file`` for dependencies is meant for a convenience for packaging +applications with possibly strictly versioned dependencies. + +Library packagers are discouraged from using overly strict (or "locked") +dependency versions in their ``dependencies`` and ``optional-dependencies``. + +Currently, when specifying ``optional-dependencies`` dynamically, all of the groups +must be specified dynamically; one can not specify some of them statically and +some of them dynamically. + +Also note that the file format for specifying dependencies resembles a ``requirements.txt`` file, +however please keep in mind that all non-comment lines must conform with :pep:`508` +(``pip``-specify syntaxes, e.g. ``-c/-r/-e`` flags, are not supported). + + +.. attention:: + When using the ``file`` directive, please make sure that all necessary + files are included in the ``sdist``. You can do that via ``MANIFEST.in`` + or using plugins such as ``setuptools-scm``. + Please have a look on :doc:`/userguide/miscellaneous` for more information. + +---- + +.. rubric:: Notes + +.. [#setupcfg-caveats] ``pip`` may allow editable install only with ``pyproject.toml`` + and ``setup.cfg``. However, this behavior may not be consistent over various ``pip`` + versions and other packaging-related tools + (``setup.py`` is more reliable on those scenarios). + +.. [#entry-points] Dynamic ``scripts`` and ``gui-scripts`` are a special case. + When resolving these metadata keys, ``setuptools`` will look for + ``tool.setuptool.dynamic.entry-points``, and use the values of the + ``console_scripts`` and ``gui_scripts`` :doc:`entry-point groups + <PyPUG:specifications/entry-points>`. + +.. [#directives] In the context of this document, *directives* are special TOML + values that are interpreted differently by ``setuptools`` (usually triggering an + associated function). Most of the times they correspond to a special TOML table + (or inline-table) with a single top-level key. + For example, you can have the ``{find = {where = ["src"], exclude=["tests*"]}}`` + directive for ``tool.setuptools.packages``, or ``{attr = "mymodule.attr"}`` + directive for ``tool.setuptools.dynamic.version``. + +.. [#attr] ``attr`` is meant to be used when the module attribute is statically + specified (e.g. as a string, list or tuple). As a rule of thumb, the + attribute should be able to be parsed with :func:`ast.literal_eval`, and + should not be modified or re-assigned. + +.. _TOML value types: https://toml.io/en/v1.0.0 diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst new file mode 100644 index 00000000..bf92f6a2 --- /dev/null +++ b/docs/userguide/quickstart.rst @@ -0,0 +1,476 @@ +========== +Quickstart +========== + +Installation +============ + +You can install the latest version of ``setuptools`` using :pypi:`pip`:: + + pip install --upgrade setuptools + +Most of the times, however, you don't have to... + +Instead, when creating new Python packages, it is recommended to use +a command line tool called :pypi:`build`. This tool will automatically download +``setuptools`` and any other build-time dependencies that your project might +have. You just need to specify them in a ``pyproject.toml`` file at the root of +your package, as indicated in the :ref:`following section <basic-use>`. + +.. _install-build: + +You can also :doc:`install build <build:installation>` using :pypi:`pip`:: + + pip install --upgrade build + +This will allow you to run the command: ``python -m build``. + +.. important:: + Please note that some operating systems might be equipped with + the ``python3`` and ``pip3`` commands instead of ``python`` and ``pip`` + (but they should be equivalent). + If you don't have ``pip`` or ``pip3`` available in your system, please + check out :doc:`pip installation docs <pip:installation>`. + + +Every python package must provide a ``pyproject.toml`` and specify +the backend (build system) it wants to use. The distribution can then +be generated with whatever tool that provides a ``build sdist``-like +functionality. + + +.. _basic-use: + +Basic Use +========= + +When creating a Python package, you must provide a ``pyproject.toml`` file +containing a ``build-system`` section similar to the example below: + +.. code-block:: toml + + [build-system] + requires = ["setuptools"] + build-backend = "setuptools.build_meta" + +This section declares what are your build system dependencies, and which +library will be used to actually do the packaging. + +In addition to specifying a build system, you also will need to add +some package information such as metadata, contents, dependencies, etc. +This can be done in the same ``pyproject.toml`` [#beta]_ file, +or in a separated one: ``setup.cfg`` or ``setup.py`` [#setup.py]_. + +The following example demonstrates a minimum configuration +(which assumes the project depends on :pypi:`requests` and +:pypi:`importlib-metadata` to be able to run): + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + name = "mypackage" + version = "0.0.1" + dependencies = [ + "requests", + 'importlib-metadata; python_version<"3.8"', + ] + + See :doc:`/userguide/pyproject_config` for more information. + +.. tab:: setup.cfg + + .. code-block:: ini + + [metadata] + name = mypackage + version = 0.0.1 + + [options] + install_requires = + requests + importlib-metadata; python_version < "3.8" + + See :doc:`/userguide/declarative_config` for more information. + +.. tab:: setup.py [#setup.py]_ + + .. code-block:: python + + from setuptools import setup + + setup( + name='mypackage', + version='0.0.1', + install_requires=[ + 'requests', + 'importlib-metadata; python_version == "3.8"', + ], + ) + + See :doc:`/references/keywords` for more information. + +Finally, you will need to organize your Python code to make it ready for +distributing into something that looks like the following +(optional files marked with ``#``):: + + mypackage + ├── pyproject.toml # and/or setup.cfg/setup.py (depending on the configuration method) + | # README.rst or README.md (a nice description of your package) + | # LICENCE (properly chosen license information, e.g. MIT, BSD-3, GPL-3, MPL-2, etc...) + └── mypackage + ├── __init__.py + └── ... (other Python files) + +With :ref:`build installed in your system <install-build>`, you can then run:: + + python -m build + +You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl`` file +in the ``dist`` directory), which you can :doc:`upload <twine:index>` to PyPI_! + +Of course, before you release your project to PyPI_, you'll want to add a bit +more information to help people find or learn about your project. +And maybe your project will have grown by then to include a few +dependencies, and perhaps some data files and scripts. In the next few sections, +we will walk through the additional but essential information you need +to specify to properly package your project. + + +.. + TODO: A previous generation of this document included a section called + "Python packaging at a glance". This is a nice title, but the content + removed because it assumed the reader had familiarity with the history of + setuptools and PEP 517. We should take advantage of this nice title and add + this section back, but use it to explain important concepts of the + ecosystem, such as "sdist", "wheel", "index". It would also be nice if we + could have a diagram for that (explaining for example that "wheels" are + built from "sdists" not the source tree). + +.. _setuppy_discouraged: +.. admonition:: Info: Using ``setup.py`` + :class: seealso + + Setuptools offers first class support for ``setup.py`` files as a configuration + mechanism. + + It is important to remember, however, that running this file as a + script (e.g. ``python setup.py sdist``) is strongly **discouraged**, and + that the majority of the command line interfaces are (or will be) **deprecated** + (e.g. ``python setup.py install``, ``python setup.py bdist_wininst``, ...). + + We also recommend users to expose as much as possible configuration in a + more *declarative* way via the :doc:`pyproject.toml <pyproject_config>` or + :doc:`setup.cfg <declarative_config>`, and keep the ``setup.py`` minimal + with only the dynamic parts (or even omit it completely if applicable). + + See `Why you shouldn't invoke setup.py directly`_ for more background. + +.. _Why you shouldn't invoke setup.py directly: https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html + + +Overview +======== + +Package discovery +----------------- +For projects that follow a simple directory structure, ``setuptools`` should be +able to automatically detect all :term:`packages <package>` and +:term:`namespaces <namespace>`. However, complex projects might include +additional folders and supporting files that not necessarily should be +distributed (or that can confuse ``setuptools`` auto discovery algorithm). + +Therefore, ``setuptools`` provides a convenient way to customize +which packages should be distributed and in which directory they should be +found, as shown in the example below: + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + # ... + [tool.setuptools.packages] + find = {} # Scan the project directory with the default parameters + + # OR + [tool.setuptools.packages.find] + # All the following settings are optional: + where = ["src"] # ["."] by default + include = ["mypackage*"] # ["*"] by default + exclude = ["mypackage.tests*"] # empty by default + namespaces = false # true by default + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + packages = find: # OR `find_namespace:` if you want to use namespaces + + [options.packages.find] # (always `find` even if `find_namespace:` was used before) + # This section is optional as well as each of the following options: + where=src # . by default + include=mypackage* # * by default + exclude=mypackage.tests* # empty by default + +.. tab:: setup.py [#setup.py]_ + + .. code-block:: python + + from setuptools import find_packages # or find_namespace_packages + + setup( + # ... + packages=find_packages( + # All keyword arguments below are optional: + where='src', # '.' by default + include=['mypackage*'], # ['*'] by default + exclude=['mypackage.tests'], # empty by default + ), + # ... + ) + +When you pass the above information, alongside other necessary information, +``setuptools`` walks through the directory specified in ``where`` (defaults to ``.``) and filters the packages +it can find following the ``include`` patterns (defaults to ``*``), then it removes +those that match the ``exclude`` patterns (defaults to empty) and returns a list of Python packages. + +For more details and advanced use, go to :ref:`package_discovery`. + +.. tip:: + Starting with version 61.0.0, setuptools' automatic discovery capabilities + have been improved to detect popular project layouts (such as the + :ref:`flat-layout` and :ref:`src-layout`) without requiring any + special configuration. Check out our :ref:`reference docs <package_discovery>` + for more information, but please keep in mind that this functionality is + still considered **beta** and might change in future releases. + + +Entry points and automatic script creation +------------------------------------------- +Setuptools supports automatic creation of scripts upon installation, that run +code within your package if you specify them as :doc:`entry points +<PyPUG:specifications/entry-points>`. +An example of how this feature can be used in ``pip``: +it allows you to run commands like ``pip install`` instead of having +to type ``python -m pip install``. + +The following configuration examples show how to accomplish this: + + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.scripts] + cli-name = "mypkg.mymodule:some_func" + +.. tab:: setup.cfg + + .. code-block:: ini + + [options.entry_points] + console_scripts = + cli-name = mypkg.mymodule:some_func + +.. tab:: setup.py [#setup.py]_ + + .. code-block:: python + + setup( + # ... + entry_points={ + 'console_scripts': [ + 'cli-name = mypkg.mymodule:some_func', + ] + } + ) + +When this project is installed, a ``cli-name`` executable will be created. +``cli-name`` will invoke the function ``some_func`` in the +``mypkg/mymodule.py`` file when called by the user. +Note that you can also use the ``entry-points`` mechanism to advertise +components between installed packages and implement plugin systems. +For detailed usage, go to :doc:`entry_point`. + + +Dependency management +--------------------- +Packages built with ``setuptools`` can specify dependencies to be automatically +installed when the package itself is installed. +The example below shows how to configure this kind of dependencies: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "docutils", + "requests <= 0.4", + ] + # ... + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + install_requires = + docutils + requests <= 0.4 + +.. tab:: setup.py [#setup.py]_ + + .. code-block:: python + + setup( + # ... + install_requires=["docutils", "requests <= 0.4"], + # ... + ) + +Each dependency is represented by a string that can optionally contain version requirements +(e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier), +and/or conditional environment markers, e.g. ``sys_platform == "win32"`` +(see :doc:`PyPUG:specifications/version-specifiers` for more information). + +When your project is installed, all of the dependencies not already installed +will be located (via PyPI), downloaded, built (if necessary), and installed. +This, of course, is a simplified scenario. You can also specify groups of +extra dependencies that are not strictly required by your package to work, but +that will provide additional functionalities. +For more advanced use, see :doc:`dependency_management`. + + +.. _Including Data Files: + +Including Data Files +-------------------- +Setuptools offers three ways to specify data files to be included in your packages. +For the simplest use, you can simply use the ``include_package_data`` keyword: + +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [tool.setuptools] + include-package-data = true + # This is already the default behaviour if your are using + # pyproject.toml to configure your build. + # You can deactivate that with `include-package-data = false` + +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + include_package_data = True + +.. tab:: setup.py [#setup.py]_ + + .. code-block:: python + + setup( + # ... + include_package_data=True, + # ... + ) + +This tells setuptools to install any data files it finds in your packages. +The data files must be specified via the |MANIFEST.in|_ file +or automatically added by a :ref:`Revision Control System plugin +<Adding Support for Revision Control Systems>`. +For more details, see :doc:`datafiles`. + + +Development mode +---------------- + +``setuptools`` allows you to install a package without copying any files +to your interpreter directory (e.g. the ``site-packages`` directory). +This allows you to modify your source code and have the changes take +effect without you having to rebuild and reinstall. +Here's how to do it:: + + pip install --editable . + +See :doc:`development_mode` for more information. + +.. tip:: + + Prior to :ref:`pip v21.1 <pip:v21-1>`, a ``setup.py`` script was + required to be compatible with development mode. With late + versions of pip, projects without ``setup.py`` may be installed in this mode. + + If you have a version of ``pip`` older than v21.1 or is using a different + packaging-related tool that does not support :pep:`660`, you might need to keep a + ``setup.py`` file in file in your repository if you want to use editable + installs. + + A simple script will suffice, for example: + + .. code-block:: python + + from setuptools import setup + + setup() + + You can still keep all the configuration in + :doc:`pyproject.toml </userguide/pyproject_config>` and/or + :doc:`setup.cfg </userguide/declarative_config>` + + +Uploading your package to PyPI +------------------------------ +After generating the distribution files, the next step would be to upload your +distribution so others can use it. This functionality is provided by +:pypi:`twine` and is documented in the :doc:`Python packaging tutorial +<PyPUG:tutorials/packaging-projects>`. + + +Transitioning from ``setup.py`` to ``setup.cfg`` +------------------------------------------------ +To avoid executing arbitrary scripts and boilerplate code, we are transitioning +into a full-fledged ``setup.cfg`` to declare your package information instead +of running ``setup()``. This inevitably brings challenges due to a different +syntax. :doc:`Here </userguide/declarative_config>` we provide a quick guide to +understanding how ``setup.cfg`` is parsed by ``setuptools`` to ease the pain of +transition. + +.. _packaging-resources: + +Resources on Python packaging +============================= +Packaging in Python can be hard and is constantly evolving. +`Python Packaging User Guide <https://packaging.python.org>`_ has tutorials and +up-to-date references that can help you when it is time to distribute your work. + + +.. |MANIFEST.in| replace:: ``MANIFEST.in`` +.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/ + + +---- + +.. rubric:: Notes + +.. [#setup.py] + New projects are advised to avoid ``setup.py`` configurations (beyond the minimal stub) + when custom scripting during the build is not necessary. + Examples are kept in this document to help people interested in maintaining or + contributing to existing packages that use ``setup.py``. + Note that you can still keep most of configuration declarative in + :doc:`setup.cfg <declarative_config>` or :doc:`pyproject.toml + <pyproject_config>` and use ``setup.py`` only for the parts not + supported in those files (e.g. C extensions). + See :ref:`note <setuppy_discouraged>`. + +.. [#beta] + Support for adding build configuration options via the ``[tool.setuptools]`` + table in the ``pyproject.toml`` file is still in **beta** stage. + See :doc:`/userguide/pyproject_config`. + +.. _PyPI: https://pypi.org |
