Metadata-Version: 2.1
Name: setuptools-build-subpackage
Version: 1.0.0
Summary: Package a subfolder as a python distribution
Home-page: https://github.com/ashb/setuptools-build-subpackage
Author: Ash Berlin-Taylor
Author-email: ash@apache.org
License: Apache License 2.0
Project-URL: Source Code, https://github.com/ashb/setuptools-build-subpackage
Project-URL: Bug Tracker, https://github.com/ashb/setuptools-build-subpackage/issues
Description: ==================================
        setuptools-build-subpackage v1.0.0
        ==================================
        
        Package a subfolder as a python distribution
        
        * Free software: Apache Software License 2.0
        
        .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
            :target: https://github.com/psf/black
        
        Installation
        ============
        
        ::
        
            pip install setuptools-build-subpackage
        
        You can also install the in-development version with::
        
            pip install https://github.com/ashb/setuptools-build-subpackage/archive/master.zip
        
        
        Usage
        =============
        
        This distribution contains a subclass of setuptools's Distribution, designed to build a "sub-module" as a stand alone distribution.
        
        It is designed to be used with `setuptools's declrative config <https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html>`_ -- i.e. where everything is defined in setup.cfg, not in setup.py
        
        For example, take the following layout::
        
            ├── example
            │   ├── __init__.py
            │   ├── sub_module_a
            │   │   ├── __init__.py
            │   │   ├── setup.cfg
            │   │   └── where.py
            │   └── sub_module_b
            │       ├── __init__.py
            │       ├── setup.cfg
            │       └── where.py
            └── setup.cfg
        
        This assumes we want ``example.sub_module_a`` and ``example.sub_module_b`` not included in the main distribution, but instead released as separate dists to PyPI.
        
        This set of classes ensures the following:
        
        - That the top level ``setup.cfg`` is not loaded, instead only the one specified from the sub-package
        - That the ``build/`` folder for each sub-package is kept clean, so files from one build don't leak in to another
        - That the ``setup.cfg`` from the sub-folder is present in the built ``sdist`` at the top level, meaning it can be installed normally.
        - That a ``stub`` setup.py file is included for compatibility with older installers
        
        Configure your main dist
        ------------------------
        
        First you should exclude the sub-packages from being included in your main dist:
        
        .. code-block:: python
        
            setup(
                ...
                packages=find_packages(exclude=['example.sub_module_*'])
            )
        
        or
        
        .. code-block:: ini
        
            [options.packages.find]
            exclude =
              example.sub_module_*
        
        Create a setup.cfg for your sub-dist
        ------------------------------------
        
        The requirements and information for the subdist are all driven off a setup.cfg -- right now a sub-``setup.py`` is not supported. (The ``setup.py`` included in the sdist will always be generated. PRs welcome if you need something else here.)
        
        See ``example/sub_module_a/setup.cfg`` in the source code for a minimal example.
        
        All file paths and module names are absolute, not relative to the location of the ``setup.cfg`` file
        
        Build the sdist/bdist
        ---------------------
        
        Run the following command:
        
        .. code-block:: bash
        
            python -m setuptools_build_subpackage \
              --subpackage-folder example/sub_module_b \
              sdist \
              bdist_wheel
        
        This will create a .tar.ga and .whl file in dist
        
        Including a license comment
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        If you need a license comment in the generated ``setup.py``, pass the ``--license-template`` option to ``sdist``
        
        
        .. code-block:: bash
        
            python -m setuptools_build_subpackage \
              --subpackage-folder example/sub_module_b \
              sdist --license-template ./LICENSE \
              bdist_wheel
        
        This argument should be a path to a plain-text license file, that will be included at the top of the generated file, each line prefixed with a python comment.
        
        Development
        ===========
        
        To run all the tests run::
        
            pip install -e '.[devel]' && pytest
        
        It is also recommended that you install pre-commit to check style rules
        
        
        Changelog
        =========
        
        1.0.0 (2021-04-23)
        ------------------
        
        * First release on PyPI.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Utilities
Requires-Python: >=3.5
Provides-Extra: devel
