Metadata-Version: 1.1
Name: pypackage
Version: 0.2.3
Summary: Pypackage looks to package python without writing a setup.py
Home-page: http://ccpgames.github.io/pypackage
Author: Adam Talsma
Author-email: se-adam.talsma@ccpgames.com
License: UNKNOWN
Download-URL: https://github.com/ccpgames/pypackage
Description: Pypackage
        =========
        
        `View this on GitHub Pages <http://ccpgames.github.io/pypackage/>`__
        
        |Build Status| |Coverage Status| |Version| |Download format| |Downloads
        this month| |Development Status| |License| |Gitter Chat|
        
        Pypackage is a collection of python packaging applications including:
        
        ::
        
            py-build
            py-develop
            py-info
            py-install
            py-setup
            py-test
        
        The goal of Pypackage is to make python packaging easier and
        faster.
        
        Wouldn't it be nice if you could just write some python, run a command,
        and have a distributable package?
        
        Well, now you can!
        
        Features
        --------
        
        -  automatic detection of python modules and packages
        -  automatic inclusion of non-python package data files, and their
           inclusion in and writing of the ``MANIFEST.in``
        -  support for three different testing frameworks (pytest, nose, and
           unittest) for use with ``setup.py test``
        -  automatic script detection (any executable file in ``./bin`` or
           ``./scripts``)
        -  automatic ``version``, ``author``, ``maintainer`` and ``email`` (s)
           detection (prefers ``__init__.py``, ``__version__.py``)
        -  curses front-end to python classifiers selection
        -  easy access to package metadata with ``py-info <package>``
        
        Example: "Hello World" application:
        -----------------------------------
        
        .. code:: bash
        
            $ mkdir hello_world
            $ cd hello_world
            $ vim hello_world.py   # write your python here... :)
            $ py-build -is
        
        The ``py-build -is`` command will take you through an interactive
        ``py-build`` session, and then save the ``setup.py`` to disk (but it
        will not run it).
        
        You can use ``py-setup`` at any time to see what Pypackage would use
        as a ``setup.py`` in the current directory's context.
        
        Metadata can be mixed in with site-wide defaults from ``$HOME/.pypackage``,
        if you want to fill in some common attributes for all your projects.
        
        Pypackage can also find and run your tests with ``python setup.py test``.
        It supports three different test runners: pytest, nose, and unittest.
        
        To be clear: pypackage does *not* replace setuptools, pip, or anything
        in the python packaging tool-chain; it only attempts to complement those
        utilities, and make python packaging a little easier.
        
        In my perfect utopian dream world, I'd see projects not have a ``setup.py``
        under source control. Instead there would only be a static metadata file.
        In the distribution version of the package, the inverse would be true.
        
        Example, write Python and send it to PyPI
        -----------------------------------------
        
        First, `configure your ~/.pypirc
        file <https://docs.python.org/2/distutils/packageindex.html#pypirc>`__
        with a ``[pypi]`` section if you haven't already. Now, assuming you lay
        out your project something like:
        
        ::
        
            ./your_project
            ./your_project/README.md
            ./your_project/pypackage.meta
            ./your_project/...
            ./your_project/your_project/__init__.py
            ./your_project/your_project/your_code.py
            ./your_project/your_project/...
        
        With pypackage installed, from ``./your_project`` run the following
        commands to send your project to PyPI for the first time:
        
        .. code:: bash
        
            $ py-build
            $ py-build -s
            $ python setup.py register
            $ twine upload dist/* || pip install twine && twine upload dist/*
        
        Every time after that, to update your package is a two step process:
        
        .. code:: bash
        
            $ py-build
            $ twine upload dist/*
        
        This will upload a binary wheel and source distribution to PyPI, so you
        can share your work with the world.
        
        The source distribution will include a ``setup.py`` and will not include
        the ``pypackage.meta`` if you use one. In this way, Pypackage does not
        create a build dependency on your distribution, but rather only on your
        source, or perhaps more specifically, your build chain and/or
        development environment. (Unless you choose to develop off of the
        distributed source version, then carry on doing your thing.)
        
        Just don't submit any patches to the ``setup.py``, because it's not a real
        thing in the source. As a project maintainer, you may even consider adding
        ``setup.py`` to the ``.gitignore`` of your pypackaged projects.
        
        pypackage.meta
        --------------
        
        Pypackage uses the ``pypackage.meta`` file in your project to fill in
        any details that it would otherwise not be able to guess. It is a JSON
        formatted file which can have any of the ``setuptools`` or ``distutils``
        setup kwargs as key/value pairs.
        
        It also has a few extra keys to extend the functionality of setuptools (most
        notably to support the ``source_label`` and ``source_url`` parameters,
        mentioned in `PEP426 <http://legacy.python.org/dev/peps/pep-0426/>`__).
        
        Below is an example of a fully-featured ``pypackage.meta`` file.
        (For a complete list of all available keys, they are the ``_KEYS`` and
        ``_PYPACKAGE_KEYS`` OrderedDicts found in the ``Config`` object;
        `view the source
        <https://github.com/ccpgames/pypackage/blob/master/pypackage/config.py>`__):
        
        .. code:: meta
        
            {
                # single line comments like so are allowed in the pypackage.meta
                # but if py-build remakes the meta (-m flag) the comments will be removed
        
                # name, if not provided, is guessed from the current directory name
                "name": "demo-package",
        
                # version, if not provided, is searched for in your source code
                "version": "1.0.1",
        
                # description becomes long_description as well unless long_description is also set
                "description": "This is a demo package",
        
                # filenames can also be used for long_description, relative path from package root
                "long_description": "README.md",
        
                "author": "Your name here",
                "author_email": "yourname@yourcompany.com",
        
                # if author is provided but maintainer is not, maintainer becomes author
                "maintainer": "Someone else",
                "maintainer_email": "someoneelse@yourcompany.com",
        
                "url": "http://yourcompany.com/yourproject",
                "download_url": "http://yourcompany.com/releases/yourproject",
        
                # for packages, you can either provide a list of package names, use
                # find_packages() with your own args/kwargs, or use pypackage's defaults.
                # for instance, both of these are valid for packages:
                "packages": ["your_package"],
                # "packages": ["find_packages(exclude=['examples', 'tests'])"],
                # if not provided, this is the default for packages:
                # "packages": ["find_packages(exclude=['test', 'tests'])"],
        
                # py_modules can be used to install top level python modules, but it will
                # also be guessed at and included if not provided (any top level .py file
                # is included by pypackage's guesswork).
                "py_modules": ["demo_module"],
        
                # scripts may be provided as relative file paths, or if not provided, pypackage
                # will guess at them. any file in either `bin` or `scripts` directory down
                # from the package root will be included (on windows) or any executable file
                # in those directories are included when building on anything that's not windows.
                "scripts": ["bin/demo_script"],
        
                # entry_points are the same syntax as you're used to. pypackage makes no guesses at these
                "entry_points": {"paste.app_factory": ["main = demo_package.web:paste"]},
        
                # a list of packages to be installed when your package is installed
                "install_requires": ["requests > 1.0.0"],
        
                # a list of packages to be installed when your package is tested
                # note if you're using test_runner you don't have to include the runner or coverage
                "tests_require": ["twisted > 15.0.0"],
        
                # list of python classifiers. you can run `py-build -R` to forcibly (re)enter
                # the curses classifiers selection process
                "classifiers": [
                    "Development Status :: 4 - Beta",
                    "Environment :: Web Environment"
                ],
        
                # ~~ PYPACKAGE ONLY KEYS ~~
                # everything above this was fairly standard, below are pypackage-specific features
        
                # test_runner can be one of three strings, "nose", "pytest", or "unittest"
                # if provided, pypackage will handle gathering and executing your tests via
                # automatic methods of whatever runner you prefer. to run your tests with
                # a test_runner in use, you can either use `py-test` or `py-build -s` to
                # create the `setup.py` and run `python setup.py test` with that.
                "test_runner": "pytest",
        
                # tests_dir can be used to provide the directory which contains the tests,
                # if automatic discovery does not work for your layout
                "tests_dir": "tests",
        
                # runner_args are arguments provided to your test_runner, if you need to
                # use custom flags, perhaps to output a JUnit XML or what have you. Note
                # that if you do provide runner_args that the default runner_args are
                # swapped out in place of what you have provided, no merging occurs.
                "runner_args": ["-vv", "--pdb"],
        
                # source_label and source_url are described in draft PEP426. they are
                # inserted into the package's metadata, which can be retrieved by using
                # `py-info <package>` on any installed package. the contents are not
                # validated to conform to any spec other than being a string
                "source_label": "5ce507eac031d4e1ccd2c34f7812240ac391d749",
        
                # same with source_url, it's only in the metadata
                "source_url": "https://yourcompany.com/commit/5ce507eac031d4e1ccd2c34f7812240ac391d749"
            }
        
        Further examples
        ----------------
        
        If your OS can run a bash script, execute ``demo.sh`` in the top level
        of this repo to create a new pypackage venv and some simple example
        packages in an ``example`` directory. From there feel free to play
        around and experiment with pypackage features and applications.
        
        
        Screenshots
        -----------
        
        The following screenshots were all taken with the ``detected_pkg`` package,
        which is created by the ``demo.sh`` script described in the further examples
        section above.
        
        Curses top level classifiers selection screen:
        
        .. image:: https://raw.githubusercontent.com/ccpgames/pypackage/gh-pages/images/top_level_post.png
            :alt: top level classifiers
            :align: center
        
        Curses development status screen with ``Beta`` selected:
        
        .. image:: https://raw.githubusercontent.com/ccpgames/pypackage/gh-pages/images/dev_status_post.png
            :alt: development status classifiers
            :align: center
        
        Interactive build process which used the above in its classifiers selection:
        
        .. image:: https://raw.githubusercontent.com/ccpgames/pypackage/gh-pages/images/interactive_build_post.png
            :alt: `py-build -si` interactive build session
            :align: center
        
        
        Copyright and License
        =====================
        
        pypackage was written by Adam Talsma
        
        Copyright (c) 2015 CCP hf.
        
        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.
        
        .. |Build Status| image:: https://travis-ci.org/ccpgames/pypackage.svg?branch=master
           :target: https://travis-ci.org/ccpgames/pypackage
        .. |Coverage Status| image:: https://coveralls.io/repos/ccpgames/pypackage/badge.svg?branch=master
           :target: https://coveralls.io/r/ccpgames/pypackage?branch=master
        .. |Version| image:: https://img.shields.io/pypi/v/pypackage.svg
           :target: https://pypi.python.org/pypi/pypackage/
        .. |Download format| image:: https://img.shields.io/badge/format-wheel-green.svg?
           :target: https://pypi.python.org/pypi/pypackage/
        .. |Downloads this month| image:: https://img.shields.io/pypi/dm/pypackage.svg
           :target: https://pypi.python.org/pypi/pypackage/
        .. |Development Status| image:: https://img.shields.io/badge/status-beta-orange.svg
           :target: https://pypi.python.org/pypi/pypackage/
        .. |License| image:: https://img.shields.io/github/license/ccpgames/pypackage.svg
           :target: https://pypi.python.org/pypi/pypackage/
        .. |Gitter Chat| image:: https://badges.gitter.im/Join%20Chat.svg
           :alt: Join the chat at https://gitter.im/ccpgames/pypackage
           :target: https://gitter.im/ccpgames/pypackage?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: System :: Archiving :: Packaging
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Utilities
