Metadata-Version: 1.1
Name: satsuki
Version: 0.1.22
Summary: Manage GitHub releases and release assets.
Home-page: https://github.com/plus3it/satsuki
Author: YakDriver
Author-email: projects@plus3it.com
License: Apache Software License 2.0
Description: =======
        Satsuki
        =======
        
        .. image:: https://img.shields.io/github/license/plus3it/satsuki.svg
            :target: ./LICENSE
            :alt: License
        .. image:: https://travis-ci.org/plus3it/satsuki.svg?branch=master
            :target: http://travis-ci.org/plus3it/satsuki
            :alt: Build Status
        .. image:: https://ci.appveyor.com/api/projects/status/9f0bdlgdc9em6bqc?svg=true
            :target: https://github.com/plus3it/satsuki
            :alt: Build Status
        .. image:: https://img.shields.io/pypi/pyversions/satsuki.svg
            :target: https://pypi.python.org/pypi/satsuki
            :alt: Python Version Compatibility
        .. image:: https://img.shields.io/pypi/v/satsuki.svg
            :target: https://pypi.python.org/pypi/satsuki
            :alt: Version
        .. image:: https://pullreminders.com/badge.svg
            :target: https://pullreminders.com?ref=badge
            :alt: Pull Reminder
        
        **Satsuki** (*pronounced SAHT-ski*) is a Python package that helps
        manage GitHub releases and release assets.
        Satsuki is especially useful paired with Continuous Integration/
        Continuous Deployment (CI/CD)
        tools such as `Travis CI <https://travis-ci.org>`_ and `AppVeyor <https://www.appveyor.com>`_.
        
        Why not just use the Travis CI GitHub Releases provider? Good question.
        The simple answer is that the provider doesn't work very well yet.
        In specific, you can't update an existing release or add files
        (assets) to a release or provide a release message and a release asset
        at the same time.
        
        Satsuki and Travis CI Example
        =============================
        
        This example shows setting up Travis CI with your GitHub OAUTH token
        for use by Satsuki, and then creating releases and uploading assets.
        
        **Step 1: Encrypt OAUTH Token**
        
        Using Travis's command line tool, encrypt your OAUTH token *with* the
        environment variable name. NOTE: Travis CI encrypts values on a repo
        by repo
        basis. Thus, a value encrypted for one repo will not work in another
        repo, even if commonly owned.
        
        .. code-block:: bash
        
            $ cd myrepodir
            $ travis encrypt SATS_TOKEN=YOUR_GITHUB_OATH_TOKEN
            Please add the following to your .travis.yml file:
        
            secure: "SBKfniOex/LRjHrN/IVQHyKquTxGRY6UxZhrPd1fMsFHu+1Jl8GGkMX8wZ8GL29S0GgIZwDVHBwu3kVcX0xJWmRrLf9kcUrN5RdbTn7KxAxqboJKLolJqXhbSE1pZBUm1IbY3BuL0hZ4oYg8KyuARnanF0PXjpJTFysYq9cYwolc4XzZ0EOXRNCSBLkcIUsULhunFHPKxaATEwUMgnOIYHkBMdfjVynuW1hqhgwAstpfhNvryir6vbZla7M3/EBTqJjuGhXTf1U6YWubGFBXNDwqIqRurMHRC0pyqc/NpEUhgFANTqs3ax/Ka0cnZAxoq99rPWe9ZtElN/GKrjJT6STPjfsaCC6ls3JFC0aorEuMMH+2pqEr7p3Llbs1OkBnZKD7aTNQxmMimZ78yq6snSM5zew9Nxjv0lytZOpHQXFtjXJtc8YcXcWylYSngMnRVnPzxFADn4udNdFZzP8+HZEkkKHJXaICu0Vx15ll4tEo1I2BJQ/ViV4sjo6KfAL3ZqC6RTjs2aqnMHu7i8DrQzYlmRXsKr2HyVudN3cgAgK5cZkJArCjxu8glY5OrFvSxjKOF1tno8Zrhne6xyBcQfVXP7gqQYQ/sUx1dqTc7XPqkB4r4OkmXH+Af7jRQahQxk04+vahtrKJX4WEYeA4teOAYN2xWsbvdrCcIvgUXNx="
        
        
        **Step 2: Add Token to Travis YAML**
        
        Now, we'll add this secure value to the ``.travis.yml`` file in our repo.
        Only Travis CI can decrypt this value now. (Although this shows Python
        as the language, Satsuki will work with projects in other languages
        as long as you install Python 3 and pip.)
        
        .. code-block:: yaml
        
            language: python
            sudo: false
            env:
              global:
                - secure: SBKfniOex/LRjHrN/IVQHyKquTxGRY6UxZhrPd1fMsFHu+1Jl8GGkMX8wZ8GL29S0GgIZwDVHBwu3kVcX0xJWmRrLf9kcUrN5RdbTn7KxAxqboJKLolJqXhbSE1pZBUm1IbY3BuL0hZ4oYg8KyuARnanF0PXjpJTFysYq9cYwolc4XzZ0EOXRNCSBLkcIUsULhunFHPKxaATEwUMgnOIYHkBMdfjVynuW1hqhgwAstpfhNvryir6vbZla7M3/EBTqJjuGhXTf1U6YWubGFBXNDwqIqRurMHRC0pyqc/NpEUhgFANTqs3ax/Ka0cnZAxoq99rPWe9ZtElN/GKrjJT6STPjfsaCC6ls3JFC0aorEuMMH+2pqEr7p3Llbs1OkBnZKD7aTNQxmMimZ78yq6snSM5zew9Nxjv0lytZOpHQXFtjXJtc8YcXcWylYSngMnRVnPzxFADn4udNdFZzP8+HZEkkKHJXaICu0Vx15ll4tEo1I2BJQ/ViV4sjo6KfAL3ZqC6RTjs2aqnMHu7i8DrQzYlmRXsKr2HyVudN3cgAgK5cZkJArCjxu8glY5OrFvSxjKOF1tno8Zrhne6xyBcQfVXP7gqQYQ/sUx1dqTc7XPqkB4r4OkmXH+Af7jRQahQxk04+vahtrKJX4WEYeA4teOAYN2xWsbvdrCcIvgUXNx=
        
        **Step 3: Setup the Travis YAML Script Step**
        
        We'll use the ``script`` step to build an application into an
        OS/machine specific binary using
        `GravityBee <https://github.com/plus3it/gravitybee>`_.
        
        .. code-block:: yaml
        
            install:
              - pip install gravitybee satsuki
            script:
              - gravitybee --src-dir src --clean
        
        
        **Step 4: Setup the Travis YAML Before Deploy Step**
        
        Next, ssign
        values to environment variables so that Satsuki can use them to
        create the release and tag. Optionally, you can
        also use
        special variables in Satsuki that will be substituted with
        values from GravityBee.  See **Variable Substitution** below.
        
        .. code-block:: yaml
        
            before_deploy:
              - export SATS_TAG=$(grep "version = " $TRAVIS_BUILD_DIR/setup.cfg | sed "s/version = //")
              - export SATS_BODY="* Here is the message for the release"
              - export SATS_FILE="mysuperapp-1.2.3-standalone-linux-x86_64"
        
        
        **Step 5: Setup the Travis YAML Deploy Step**
        
        Everything should be set now to deploy.
        
        .. code-block:: yaml
        
            deploy:
              - provider: script
                script: satsuki
                skip_cleanup: true
                on:
                  branch: master
                  repo: YakDriver/mysuperapp
                  python: "3.6"
        
        
        Now if you've enabled your repo on Travis CI, when you commit to the
        master branch, if all goes well, you'll get a release with your binary
        file associated with it.
        
        
        Reference
        =========
        
        Satsuki can be used with command line (CL) options or environment
        variables, or a mix of both. If both are provided, command line
        options take precedence.
        
        
        Options
        -------
        
        Using Satsuki, you can create releases. A release is a GitHub feature.
        However, a release is related to a tag, which is a pure Git feature. (If
        the tag doesn't exist, Satsuki will create it along with the release.)
        You can also create assets (e.g., binary files) that are
        associated with releases. Thus Satsuki has options that relate to each:
        Asset ==> Release ==> Tag.
        
        Options from each, tag, release, and asset, can be provided at
        the same time,
        and Satsuki
        will attempt to act appropriately on each. For example, in one
        command you can create a tag, release, and asset.
        
        Release/Satsuki Related
        -----------------------
        
        Local logging can be configured in ``satsuki/logging.conf``.
        
        ================  ===============   ==========================================
        ENV VAR           CL Options        Desciption
        ================  ===============   ==========================================
        SATS_TOKEN        --token           **[Required]** An OAUTH token with
                                            repo access.
        SATS_COMMAND      -c, --command     The operation to perform on the GitHub
                                            release. Choose from ``upsert`` or
                                            ``delete``. If ``delete`` is selected and a
                                            file is provided, the file (release
                                            asset) is deleted instead of the release.
                                            *Default:* ``upsert``
        SATS_RECREATE_OK  --recreate        **[Flag]** Indicates whether a release
                                            commitish can be updated by deleting
                                            and recreating the release. Otherwise,
                                            a release cannot be updated with a new
                                            commit SHA. If this flag is set,
                                            ``--include-tag`` is implied.
                                            *Default: not*
        SATS_SLUG         -s, --slug        **[Required]** Either repo and user or
                                            the slug (in the form user/repo) must be
                                            provided. *If not provided, it will default
                                            to the value provided by Travis CI, Azure
                                            Pipelines or AppVeyor, if any.*
        SATS_REPO         -r, --repo        **[Required]** The GitHub repository to
                                            work with.
        SATS_USER         -u, --user        **[Required]** The owner of the repository
                                            to work with.
        SATS_REL_NAME     -n, --rel-name    The name of the release. **Available for
                                            variable substitution.
                                            See below.**
                                            *Default: tag name*
        SATS_LATEST       --latest          **[Required][Flag]** Either this option
                                            *OR* ``--tag`` must be used.
                                            When used, Satsuki will perform any
                                            operations on the latest release.
                                            *Default: Not*
        SATS_BODY         -b, --body        The message that shows up with releases.
                                            **Available for variable substitution.
                                            See below.**
                                            *Default: Release <tag>*
        SATS_PRE          -p, --pre         **[Flag]** Whether or not this release
                                            is a prerelease. *Default: Not*
        SATS_DRAFT        -d, --draft       **[Flag]** Whether or not this release
                                            is a draft. *Default: Not*
        SATS_FORCE        --force           **[Flag]** Force Satsuki to delete items
                                            when normally it would not. **CAUTION:**
                                            You could easily delete every
                                            release in your repository with this.
                                            *Default: Not*
        ================  ===============   ==========================================
        
        
        Tag Related
        -----------
        
        ================  ===============   ==========================================
        ENV VAR           CL Options        Desciption
        ================  ===============   ==========================================
        SATS_TAG          -t, --tag         **[Required]** Either the tag
                                            *OR* the ``--latest`` option must be
                                            provided. If both are used, tag
                                            takes precedence. In finding existing
                                            releases, the "tag" value may be either
                                            the release ID (e.g., 10746271) or tag
                                            name (e.g., v0.1.0). However, if a
                                            release ID is provided, and it does not
                                            exist, an error will be thrown to avoid
                                            creating a tag with an ID-like name.
                                            **Available for variable substitution.
                                            See below.**
                                            *If not provided,
                                            will default
                                            to the value provided by Travis CI or
                                            AppVeyor, if any.*
        SATS_COMMITISH    --commitish       Can be any branch or commit SHA. Unused
                                            if the Git tag already exists.
                                            *If not provided, it will
                                            default
                                            to the TRAVIS_COMMIT environment variable
                                            provided by
                                            Travis CI or BUILD_SOURCEVERSION from Azure
                                            Pipelines or APPVEYOR_REPO_COMMIT from
                                            AppVeyor, if any. If none is provided,
                                            GitHub will default to the default branch.*
        SATS_INCLUDE_TAG  --include-tag     Whether to delete the tag when deleting the
                                            release. If the provided tag does not match
                                            a release, the tag will be deleted. If the
                                            tag includes a POSIX-style filename pattern
                                            match, all tags which aren't associated
                                            with releases will be deleted. This is
                                            handy for cleaning up tags. If you have
                                            many tags to cleanup, you may need to run
                                            this multiple times to complete the
                                            cleaning. *Default: Not*
        ================  ===============   ==========================================
        
        
        Asset Related
        -------------
        
        These options can be used multiple times. If there is one label or one MIME
        type, and multiple files, the same label and MIME type will be applied to each
        file. Otherwise, there must be the same number of labels and/or MIME types as
        files, or an error will be thrown.
        
        ================  ===============   ==========================================
        ENV VAR           CL Options        Desciption
        ================  ===============   ==========================================
        SATS_FILE         -f, --file        File(s) to be uploaded as release asset(s).
                                            If the file name contains an asterik (*)
                                            it will be treated as a POSIX-style glob
                                            and all matching files will be uploaded.
                                            This option can be used multiple times
                                            to upload multiple files.
                                            *Default: No file is uploaded.*
        SATS_LABEL        -l, --label       Label to display for files instead of the
                                            file name. Not recommended with multiple
                                            file upload since all will share the same
                                            label. **Available for variable
                                            substitution.
                                            See below.** *Default: GitHub will
                                            use the raw
                                            file name.*
        SATS_MIME         -m, --mime        The mime type for files. *Default:
                                            A guess of the file type or*
                                            ``application/octet-stream`` *if all else
                                            fails.*
        SATS_FILE_SHA     --file-sha        Whether to create SHA256 hashes for upload
                                            files, and either append them to the file
                                            label or upload them in a separate file.
                                            Valid options are: ``none``, ``file``, and
                                            ``label``. *Default: none*
        SATS_FILES_FILE   --files-file      Name of JSON file with information about
                                            file(s) to upload.
                                            See below.
                                            *Default: Will look for*
                                            ``gravitybee-files.json``
        ================  ===============   ==========================================
        
        
        Variable Substitution
        ---------------------
        
        For certain values, you can optionally include variables
        that will be
        substituted using information from GravityBee.
        Whether variables are replaced depends
        on all the following conditions being met:
        
        * The GravityBee info file (``gravitybee-info.json``) is in
          the current directory.
        * The file is correctly formatted JSON.
        * The file uses the correct structure defined by GravityBee.
        * The variables within the environment variables are spelled
          correctly and not
          replaced prior to getting to Satsuki (e.g., by the shell
          or OS).
        
        If you're having trouble getting substitutions to work,
        try displaying environment variables (e.g., using
        ``env`` on POSIX systems or ``SET`` on Windows) to make sure
        $s haven't been replaced. On POSIX, use single quotes when setting
        environment variables to prevent premature substitution.
        
        These are the variables you can use.
        
        =====================   ==========================================
        VARIABLE                Desciption
        =====================   ==========================================
        $gb_pkg_ver             The version of the package extracted by
                                GravityBee from setup.py or setup.cfg.
        $gb_pkg_name            The name of the package extracted by
                                GravityBee from setup.py or setup.cfg,
                                which is often the application name.
        $gb_pkg_name_lower      Same as $gb_pkg_name but lowercase.
        $gb_sa_app              The name of the binary file, standalone
                                application created by GravityBee.
        =====================   ==========================================
        
        An example of using substitution.
        
        .. code-block::
        
            $ export SATS_TAG='$gb_pkg_ver' # will be replaced with 4.2.6, for example
        
        
        The Files File
        --------------
        
        Satsuki also accepts a JSON-formatted file containing information about
        assets to be uploaded (see the ``--files-file`` option above). The file
        can contain information about multiple files and should contain
        information about files
        accessible to Satsuki, with paths relative to the directory in which
        Satsuki is run. A file in the correct format is generated by
        `GravityBee <https://github.com/plus3it/gravitybee>`_.
        
        Satsuki will always look in the current directory for a GravityBee
        files file (``gravitybee-files.json``). If found, Satsuki will
        upload the specified files. To avoid this behavior, remove a
        GravityBee files file from the current directory. You can also use
        a GravityBee files file in another location, besides the current
        directory, by using the ``--files-file`` flag.
        
        This is an example of the format.
        
        .. code-block::
        
            [{'filename': 'gbtestapp-4.2.6-standalone-osx-x86_64',
              'label': 'gbtestapp Standalone Executable (gbtestapp-4.2.6-standalone-osx-x86_64) [GravityBee Build]',
              'mime-type': 'application/x-executable',
              'path': '/path/to/file/gbtestapp-4.2.6-standalone-osx-x86_64'}]
        
        
        Command-Line Examples
        ---------------------
        
        Here is an example of using Satsuki to clean up tags.
        This command will delete all tags not connected to a release that
        match the pattern ``Test-*``. To be able to clean tags,
        Satsuki must be run from the ``git`` directory of the repo.
        
        .. code-block::
        
            $ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
            --tag Test-* -c delete -v
        
        
        Delete the release asset with the filename
        ``release-asset.exe`` from the release tagged with ``Test-ve8226c``.
        
        .. code-block::
        
            $ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
            --tag Test-ve8226c -c delete -v --file release-asset.exe
        
        
        Create a new release and tag called ``testtag`` based
        on the given commit SHA, and upload the file ``release-asset.exe`` as an
        asset of the new release.
        
        .. code-block::
        
            $ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
            --tag testtag --commitish 42b8b9f3f44e0a11071cd3c56eaed29a305c3339 \
            -v --file release-asset.exe
        
        Delete the release called ``1.2.3``.
        
        .. code-block::
        
            $ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
            --tag 1.2.3 -c delete -v
        
        Delete the release and local and/or remote tags called ``1.2.3``.
        
        .. code-block::
        
            $ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
            --tag 1.2.3 -c delete -v --include-tag
        
        Delete ALL releases and local and/or remote tags matching ``Test-*``.
        **USE CAUTION!**
        
        .. code-block::
        
            $ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
            --tag Test-* -v -c delete --include-tag --force
        
        
        
        The First Confirmed Upload SHA
        ------------------------------
        
        ``25c2f15b0c332bf58d5e625f54525873bcddc2083578b335fdc4a1be8d79edda``
        
Platform: Linux
Platform: Windows
Platform: Darwin
Platform: MacOS
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
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 :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
