diff --git a/README.md b/README.md deleted file mode 100644 index 6fe378a..0000000 --- a/README.md +++ /dev/null @@ -1,155 +0,0 @@ -# pypicloud-tools - -[View this on GitHub Pages](http://ccpgames.github.io/pypicloud-tools/) - -[![Build Status](https://travis-ci.org/ccpgames/pypicloud-tools.png?branch=master)](https://travis-ci.org/ccpgames/pypicloud-tools) -[![Coverage Status](https://coveralls.io/repos/ccpgames/pypicloud-tools/badge.svg?branch=master)](https://coveralls.io/r/ccpgames/pypicloud-tools?branch=master) -[![Version](https://img.shields.io/pypi/v/pypicloud-tools.svg)](https://pypi.python.org/pypi/pypicloud-tools/) -[![Download format](https://img.shields.io/badge/format-wheel-green.svg?)](https://pypi.python.org/pypi/pypicloud-tools/) -[![Downloads this month](https://img.shields.io/pypi/dm/pypicloud-tools.svg)](https://pypi.python.org/pypi/pypicloud-tools/) -[![Development Status](https://img.shields.io/badge/status-beta-orange.svg)](https://pypi.python.org/pypi/pypicloud-tools/) -[![License](https://img.shields.io/github/license/ccpgames/pypicloud-tools.svg)](https://pypi.python.org/pypi/pypicloud-tools/) - -Tools to bypass a PyPICloud installation and communicate directly with S3 - - -## Utilities - -### Upload - -Uploads file(s) to the PyPICloud S3 bucket directly and performs an admin API call to rebuild the PyPICloud index after. - -Example: - -```bash -$ upload dist/* -Uploading example_project/example-project-0.0.1.tar.gz .....1 done! -Uploading example_project/example_project-0.0.1-py2-none-any.whl .....1 done! -Uploading example_project/example_project-0.0.1-py2.7.egg ......1 done! -PyPICloud server at http://your.pypicloud.server/pypi updated -``` - -The numbers displayed are the amount of 50MB chunks you've sent to S3 as they send. It's fine if the file names use altering hypens/underscores per release type like you see above, they only need to match the initial part of the key before the `/` to be considered the same package. - -### Download - -Downloads the latest or a specific version directly from S3. Does not talk to PyPICloud and does not install the downloaded package. You can use pip to do either/both of those things. - -Also possible with the download command is the `--url` flag to only print a download URL (usable for 5 minutes). - -By default, if there are multiple releases of the same package+release, download will prefer wheels, then eggs, then source distributions. You can override that behavior with the `--egg` and `--src` flags. - -Examples: - -```bash -$ download example_project=0.0.1 -example_project-0.0.1-py2-none-any.whl -``` - -```bash -$ download example_project --egg -example_project-0.0.1-py2.7.egg -``` - -Pipes and redirects work like you'd expect: - -```bash -$ download example_project --src | tar -xzf - -``` - -### List - -Lists a package's releases, or releases of a package at a specific version. Again, talks straight to S3 and bypasses the PyPICloud installation. - -Example: - -```bash -$ list example_project -example-project-0.0.1.tar.gz -example_project-0.0.1-py2.7.egg -example_project-0.0.1-py2-none-any.whl -``` - -Listing multiple packages or packages with a version specifier is also supported. - -When called without any arguments, `list` will display all known packages. - - -### Rehost - -Rehosts an upstream package from PyPI into the pypicloud installation. This can be handy if you have pypicloud clients which only have access to it and s3 but not the rest of the internet. - -Example: - -```bash -$ rehost requests==1.0.0 -Collecting requests==1.0.0 - Downloading requests-1.0.0.tar.gz (335kB) - 100% |████████████████████████████████| 335kB 929kB/s - Saved /var/folders/53/kl4v4_9509ng148kp_pwmc5h0000gn/T/tmpuj5JUJ/requests-1.0.0.tar.gz -Successfully downloaded requests -Uploading requests/requests-1.0.0.tar.gz ............1 done! -PyPICloud server at http://your_pypicloud_server/pypi updated -``` - -If a specific version is not provided, the latest will be used. Multiple packages can be used in the same command. - - -## Installation - -### Simple - -```bash -$ pip install pypicloud-tools -``` - -### From source - -```bash -$ git clone https://github.com/ccpgames/pypicloud-tools.git -$ cd pypicloud-tools -$ python setup.py install -``` - - -## Configuration - -Configuration for pypicloud-tools piggybacks on your `~/.pypirc` file. You can specify an alternate config file with the `--config` flag, but it must be in the same syntax. That syntax is: - -```conf -[pypicloud] - repository:http://your.pypicloud.server/pypi - username:admin - password:hunter7 - bucket:your_bucket - access:some_key - secret:other_key - acl:optional_acl -``` - -The key **must** be `pypicloud`, it is the only key pypicloud-tools will look at. The username/password combination should have admin credentials on the PyPICloud installation as it needs to call `/admin/rebuild` after a succesful upload. - - -# Copyright and License - -pypicloud-tools 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. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..7d8fea2 --- /dev/null +++ b/README.rst @@ -0,0 +1,195 @@ +pypicloud-tools +=============== + +`View this on GitHub +Pages `__ + +|Build Status| |Coverage Status| |Version| |Download format| |Downloads +this month| |Development Status| |License| + +Tools to bypass a PyPICloud installation and communicate directly with +S3 + +Utilities +--------- + +Upload +~~~~~~ + +Uploads file(s) to the PyPICloud S3 bucket directly and performs an +admin API call to rebuild the PyPICloud index after. + +Example: + +.. code:: bash + + $ upload dist/* + Uploading example_project/example-project-0.0.1.tar.gz .....1 done! + Uploading example_project/example_project-0.0.1-py2-none-any.whl .....1 done! + Uploading example_project/example_project-0.0.1-py2.7.egg ......1 done! + PyPICloud server at http://your.pypicloud.server/pypi updated + +The numbers displayed are the amount of 50MB chunks you've sent to S3 as +they send. It's fine if the file names use altering hypens/underscores +per release type like you see above, they only need to match the initial +part of the key before the ``/`` to be considered the same package. + +Download +~~~~~~~~ + +Downloads the latest or a specific version directly from S3. Does not +talk to PyPICloud and does not install the downloaded package. You can +use pip to do either/both of those things. + +Also possible with the download command is the ``--url`` flag to only +print a download URL (usable for 5 minutes). + +By default, if there are multiple releases of the same package+release, +download will prefer wheels, then eggs, then source distributions. You +can override that behavior with the ``--egg`` and ``--src`` flags. + +Examples: + +.. code:: bash + + $ download example_project=0.0.1 + example_project-0.0.1-py2-none-any.whl + +.. code:: bash + + $ download example_project --egg + example_project-0.0.1-py2.7.egg + +Pipes and redirects work like you'd expect: + +.. code:: bash + + $ download example_project --src | tar -xzf - + +List +~~~~ + +Lists a package's releases, or releases of a package at a specific +version. Again, talks straight to S3 and bypasses the PyPICloud +installation. + +Example: + +.. code:: bash + + $ list example_project + example-project-0.0.1.tar.gz + example_project-0.0.1-py2.7.egg + example_project-0.0.1-py2-none-any.whl + +Listing multiple packages or packages with a version specifier is also +supported. + +When called without any arguments, ``list`` will display all known +packages. + +Rehost +~~~~~~ + +Rehosts an upstream package from PyPI into the pypicloud installation. +This can be handy if you have pypicloud clients which only have access +to it and s3 but not the rest of the internet. + +Example: + +.. code:: bash + + $ rehost requests==1.0.0 + Collecting requests==1.0.0 + Downloading requests-1.0.0.tar.gz (335kB) + 100% |████████████████████████████████| 335kB 929kB/s + Saved /var/folders/53/kl4v4_9509ng148kp_pwmc5h0000gn/T/tmpuj5JUJ/requests-1.0.0.tar.gz + Successfully downloaded requests + Uploading requests/requests-1.0.0.tar.gz ............1 done! + PyPICloud server at http://your_pypicloud_server/pypi updated + +If a specific version is not provided, the latest will be used. Multiple +packages can be used in the same command. + +Installation +------------ + +Simple +~~~~~~ + +.. code:: bash + + $ pip install pypicloud-tools + +From source +~~~~~~~~~~~ + +.. code:: bash + + $ git clone https://github.com/ccpgames/pypicloud-tools.git + $ cd pypicloud-tools + $ python setup.py install + +Configuration +------------- + +Configuration for pypicloud-tools piggybacks on your ``~/.pypirc`` file. +You can specify an alternate config file with the ``--config`` flag, but +it must be in the same syntax. That syntax is: + +.. code:: conf + + [pypicloud] + repository:http://your.pypicloud.server/pypi + username:admin + password:hunter7 + bucket:your_bucket + access:some_key + secret:other_key + acl:optional_acl + +The key **must** be ``pypicloud``, it is the only key pypicloud-tools +will look at. The username/password combination should have admin +credentials on the PyPICloud installation as it needs to call +``/admin/rebuild`` after a succesful upload. + +Copyright and License +===================== + +pypicloud-tools 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/pypicloud-tools.png?branch=master + :target: https://travis-ci.org/ccpgames/pypicloud-tools +.. |Coverage Status| image:: https://coveralls.io/repos/ccpgames/pypicloud-tools/badge.svg?branch=master + :target: https://coveralls.io/r/ccpgames/pypicloud-tools?branch=master +.. |Version| image:: https://img.shields.io/pypi/v/pypicloud-tools.svg + :target: https://pypi.python.org/pypi/pypicloud-tools/ +.. |Download format| image:: https://img.shields.io/badge/format-wheel-green.svg? + :target: https://pypi.python.org/pypi/pypicloud-tools/ +.. |Downloads this month| image:: https://img.shields.io/pypi/dm/pypicloud-tools.svg + :target: https://pypi.python.org/pypi/pypicloud-tools/ +.. |Development Status| image:: https://img.shields.io/badge/status-beta-orange.svg + :target: https://pypi.python.org/pypi/pypicloud-tools/ +.. |License| image:: https://img.shields.io/github/license/ccpgames/pypicloud-tools.svg + :target: https://pypi.python.org/pypi/pypicloud-tools/ diff --git a/setup.py b/setup.py index 0859395..35fd4df 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,7 @@ """pypicloud-tools setup.py""" +import io from setuptools import setup from setuptools.command.test import test as TestCommand @@ -25,6 +26,10 @@ def run_tests(self): raise SystemExit(errno) +with io.open("README.rst", "r", encoding="utf-8") as openreadme: + long_description = openreadme.read() + + setup( name="pypicloud-tools", version="0.0.5", @@ -47,6 +52,8 @@ def run_tests(self): ], tests_require=["pytest", "pytest-cov", "mock"], cmdclass={"test": PyTest}, + description="Tools to bypass PyPICloud and work with S3 directly", + long_description=long_description, classifiers=[ "Development Status :: 4 - Beta", "Environment :: Console",