././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.1096733 python-swiftclient-3.13.1/0000775000175000017500000000000000000000000015474 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/.coveragerc0000664000175000017500000000011000000000000017605 0ustar00zuulzuul00000000000000[run] branch = True source = swiftclient [report] ignore_errors = True ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/.functests0000775000175000017500000000042700000000000017521 0ustar00zuulzuul00000000000000#!/bin/bash set -e export OS_TEST_PATH='test.functional' export PYTHON='coverage run --source swiftclient --parallel-mode' stestr run --concurrency=1 RET=$? coverage combine coverage html -d cover coverage xml -o cover/coverage.xml coverage report -m rm -f .coverage exit $RET ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/.mailmap0000664000175000017500000001331600000000000017121 0ustar00zuulzuul00000000000000Greg Holt gholt Greg Holt gholt Greg Holt gholt Greg Holt gholt Greg Holt Greg Holt John Dickinson Michael Barton Michael Barton Michael Barton Mike Barton Clay Gerrard Clay Gerrard Clay Gerrard Clay Gerrard clayg David Goetz David Goetz Anne Gentle Anne Gentle annegentle Fujita Tomonori Greg Lange Greg Lange Chmouel Boudjnah Gaurav B. Gangalwar gaurav@gluster.com <> Joe Arnold Kapil Thangavelu kapil.foss@gmail.com <> Samuel Merritt Morita Kazutaka Zhongyue Luo Russ Nelson Marcelo Martins Andrew Clay Shafer Soren Hansen Soren Hansen Ye Jia Xu monsterxx03 Victor Rodionov Florian Hines Jay Payne Doug Weimer Li Riqiang lrqrun Cory Wright Julien Danjou David Hadas Yaguang Wang ywang19 Liu Siqi dk647 James E. Blair Kun Huang Michael Shuler Ilya Kharin Dmitry Ukov Ukov Dmitry Tom Fifield Tom Fifield Sascha Peilicke Sascha Peilicke Zhenguo Niu Peter Portante Christian Schwede Christian Schwede Constantine Peresypkin Madhuri Kumari madhuri Morgan Fainberg Hua Zhang Yummy Bian Alistair Coles Alistair Coles Tong Li Paul Luse Yuan Zhou Jola Mirecka Ning Zhang Mauro Stettler Pawel Palucki Guang Yee Jing Liuqing Lorcan Browne Eohyung Lee Harshit Chitalia Richard Hawkins Sarvesh Ranjan Minwoo Bae Minwoo B Jaivish Kothari Michael Matur Kazuhiro Miyahara Alexandra Settle Mark Seger Donagh McCabe Stuart McLaren Alexis Lee Stanislaw Pitucha Mahati Chamarthy Peter Lisak Doug Hellmann Ondrej Novy James Nzomo Alessandro Pilotti Marek Kaleta Andreas Jaeger Shashi Kant Nandini Tata Flavio Percoco Timur Alperovich Thiago da Silva ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/.manpages0000775000175000017500000000054500000000000017277 0ustar00zuulzuul00000000000000#!/bin/sh RET=0 for MAN in doc/manpages/* ; do OUTPUT=$(LC_ALL=en_US.UTF-8 MANROFFSEQ='' MANWIDTH=80 man --warnings -E UTF-8 -l \ -Tutf8 -Z "$MAN" 2>&1 >/dev/null) if [ -n "$OUTPUT" ] ; then RET=1 echo "$MAN:" echo "$OUTPUT" fi done if [ "$RET" -eq "0" ] ; then echo "All manpages are fine" fi exit "$RET" ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/.stestr.conf0000664000175000017500000000007500000000000017747 0ustar00zuulzuul00000000000000[DEFAULT] test_path=${OS_TEST_PATH:-./test/unit} top_dir=./ ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/.unittests0000775000175000017500000000020300000000000017535 0ustar00zuulzuul00000000000000#!/bin/bash set -e python setup.py testr --coverage --testr-args="test.unit" RET=$? coverage report -m rm -f .coverage exit $RET ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/.zuul.yaml0000664000175000017500000000407500000000000017443 0ustar00zuulzuul00000000000000- job: name: swiftclient-swift-functional parent: swift-dsvm-functional description: | Run swift's functional tests with python-swiftclient installed from source instead as package from PyPI. # Ensure that we install python-swiftclient from git and # do not install from pypi. This is needed since the parent # job sets zuul_work_dir to the swift directory and uses tox # for installation. required-projects: - opendev.org/openstack/python-swiftclient - job: name: swiftclient-functional parent: swift-dsvm-functional description: | Run functional tests of python-swiftclient with python-swiftclient installed from source instead as package from PyPI. required-projects: - opendev.org/openstack/python-swiftclient vars: # Override value from parent job to use swiftclient tests zuul_work_dir: "{{ zuul.projects['opendev.org/openstack/python-swiftclient'].src_dir }}" # swift can use different tox env names tox_envlist: func - job: name: swiftclient-functional-py2 parent: swiftclient-functional nodeset: openstack-single-node-bionic description: | Run functional tests of python-swiftclient under Python 2 vars: devstack_localrc: # devstack dropped support for bionic, but we want it for easier py2 support. # Set this so we install anyway. FORCE: "yes" tox_envlist: py2func - project: templates: - check-requirements - lib-forward-testing-python3 - openstack-python-jobs - openstack-python3-yoga-jobs - publish-openstack-docs-pti - release-notes-jobs-python3 check: jobs: - swiftclient-swift-functional - swiftclient-functional - swiftclient-functional-py2 - openstack-tox-py39: voting: true gate: jobs: - swiftclient-swift-functional - swiftclient-functional - swiftclient-functional-py2 - openstack-tox-py39: voting: true post: jobs: - openstack-tox-cover ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/AUTHORS0000664000175000017500000001461000000000000016546 0ustar00zuulzuul00000000000000Alessandro Pilotti (ap@pilotti.it) Alex Gaynor (alex.gaynor@gmail.com) Alex Schultz (aschultz@redhat.com) Alexandra Settle (alexandra.settle@rackspace.com) Alexis Lee (lxsli@hpe.com) Alistair Coles (alistairncoles@gmail.com) Andreas Jaeger (aj@suse.de) Andrew Welleck (awellec@us.ibm.com) Andy McCrae (andy.mccrae@gmail.com) Anh Tran (anhtt@vn.fujitsu.com) Anne Gentle (anne@openstack.org) Ben McCann (ben@benmccann.com) Cedric Brandily (zzelle@gmail.com) Chaozhe.Chen (chaozhe.chen@easystack.cn) Charles Hsu (charles0126@gmail.com) Chen (dstbtgagt@foxmail.com) Cheng Li (shcli@cn.ibm.com) Chmouel Boudjnah (chmouel@enovance.com) Chris Buccella (chris.buccella@antallagon.com) Christian Berendt (berendt@b1-systems.de) Christian Schwede (cschwede@redhat.com) Christopher Bartz (bartz@dkrz.de) Chuck Short (chuck.short@canonical.com) Clark Boylan (clark.boylan@gmail.com) Claudiu Belu (cbelu@cloudbasesolutions.com) Clay Gerrard (clay.gerrard@gmail.com) Clint Byrum (clint@fewbar.com) Corey Bryant (corey.bryant@canonical.com) Dan Prince (dprince@redhat.com) Daniel Wakefield (daniel.wakefield@hp.com) Darrell Bishop (darrell@swiftstack.com) David Goetz (david.goetz@rackspace.com) David Kranz (david.kranz@qrclab.com) David Shrewsbury (shrewsbury.dave@gmail.com) Davide Guerri (davide.guerri@hp.com) Dean Troyer (dtroyer@gmail.com) Dirk Mueller (dirk@dmllr.de) Donagh McCabe (donagh.mccabe@hpe.com) Doug Hellmann (doug@doughellmann.com) EdLeafe (ed@leafe.com) Erik Olof Gunnar Andersson (eandersson@blizzard.com) Fabien Boucher (fabien.boucher@enovance.com) Feng Liu (mefengliu23@gmail.com) Flavio Percoco (flaper87@gmail.com) Florent Flament (florent.flament-ext@cloudwatt.com) Greg Holt (gholt@rackspace.com) Greg Lange (greglange@gmail.com) groqez (groqez@yopmail.net) Hangdong Zhang (hdzhang@fiberhome.com) Hemanth Makkapati (hemanth.makkapati@mailtrust.com) hgangwx (hgangwx@cn.ibm.com) Hirokazu Sakata (h.sakata@staff.east.ntt.co.jp) Hiroshi Miura (miurahr@nttdata.co.jp) howardlee (lihongweibj@inspur.com) Hu Bing (hubingsh@cn.ibm.com) Ian Cordasco (ian.cordasco@rackspace.com) jacky06 (zhang.min@99cloud.net) Jaivish Kothari (jaivish.kothari@nectechnologies.in) Jakub Krajcovic (jakub.krajcovic@gmail.com) James Nzomo (james@tdt.rocks) Jamie Lennox (jamielennox@gmail.com) Jeremy Stanley (fungi@yuggoth.org) Ji-Wei (ji.wei3@zte.com.cn) Jian Zhang (jian.zhang@intel.com) Jing Liuqing (jing.liuqing@99cloud.net) Jiří Suchomel (jsuchome@suse.cz) Joel Wright (joel.wright@sohonet.com) John Dickinson (me@not.mn) Jola Mirecka (jola.mirecka@hp.com) Josh Gachnang (josh@pcsforeducation.com) Juan J. Martinez (juan@memset.com) Jude Job (judeopenstack@gmail.com) Julien Danjou (julien@danjou.info) kangyufei (kangyf@inspur.com) Kazufumi Noto (noto.kazufumi@gmail.com) Kota Tsuyuzaki (tsuyuzaki.kota@lab.ntt.co.jp) Kun Huang (gareth@unitedstack.com) Leah Klearman (lklrmn@gmail.com) Li Riqiang (lrqrun@gmail.com) lingyongxu (lyxu@fiberhome.com) liuyamin (liuyamin@fiberhome.com) Luis de Bethencourt (luis@debethencourt.com) M V P Nitesh (m.nitesh@nectechnologies.in) Mahati Chamarthy (mahati.chamarthy@gmail.com) Marek Kaleta (marek.kaleta@firma.seznam.cz) Mark Seger (mark.seger@hpe.com) Mark Washenberger (mark.washenberger@rackspace.com) Martin Geisler (martin@geisler.net) Matthew Oliver (matt@oliver.net.au) Matthieu Huin (mhu@enovance.com) Mike Widman (mwidman@endurancewindpower.com) Min Min Ren (rminmin@cn.ibm.com) mmcardle (mark.mcardle@sohonet.com) Mohit Motiani (mohit.motiani@intel.com) Monty Taylor (mordred@inaugust.com) Nandini Tata (nandini.tata@intel.com) Nelson Marcos (nelsonmarcos@gmail.com) Nguyen Hai (nguyentrihai93@gmail.com) Nguyen Hai Truong (truongnh@vn.fujitsu.com) Nguyen Hung Phuong (phuongnh@vn.fujitsu.com) Nick Craig-Wood (nick@craig-wood.com) Ondrej Novy (ondrej.novy@firma.seznam.cz) Pallavi (pallavi.s@nectechnologies.in) Paul Belanger (pabelanger@redhat.com) Paulo Ewerton (pauloewerton@lsd.ufcg.edu.br) pengyuesheng (pengyuesheng@gohighsec.com) Pete Zaitcev (zaitcev@kotori.zaitcev.us) Peter Lisak (peter.lisak@firma.seznam.cz) Petr Kovar (pkovar@redhat.com) Pradeep Kumar Singh (pradeep.singh@nectechnologies.in) Pratik Mallya (pratik.mallya@gmail.com) qingszhao (zhao.daqing@99cloud.net) Qiu Yu (qiuyu@ebaysf.com) Ray Chen (oldsharp@163.com) ricolin (rico.l@inwinstack.com) Romain Hardouin (romain_hardouin@yahoo.fr) Sahid Orentino Ferdjaoui (sahid.ferdjaoui@cloudwatt.com) SaiKiran (saikiranveeravarapu@gmail.com) Sam Morrison (sorrison@gmail.com) Samuel Merritt (sam@swiftstack.com) Sean Dague (sean@dague.net) Sébastien Blaisot (sebastien@blaisot.org) Sergey Gotliv (sgotliv@redhat.com) Sergio Cazzolato (sergio.j.cazzolato@intel.com) Shane Wang (shane.wang@intel.com) shangxiaobj (shangxiaobj@inspur.com) Shashi Kant (shashi.kant@nectechnologies.in) Shashirekha Gundur (shashirekha.j.gundur@intel.com) shu-mutou (shu-mutou@rf.jp.nec.com) Stanislav Vitkovskiy (stas.vitkovsky@gmail.com) Stanislaw Pitucha (stanislaw.pitucha@hpe.com) Steve Martinelli (stevemar@ca.ibm.com) Steven Hardy (shardy@redhat.com) Stuart McLaren (stuart.mclaren@hpe.com) sunjia (sunjia@inspur.com) Sushil Kumar (sushil.kumar2@globallogic.com) tanlin (lin.tan@intel.com) Taurus Cheung (Taurus.Cheung@harmonicinc.com) TheSriram (sriram@klusterkloud.com) Thiago da Silva (thiagodasilva@gmail.com) Thomas Goirand (thomas@goirand.fr) Tihomir Trifonov (t.trifonov@gmail.com) Tim Burke (tim.burke@gmail.com) Timur Alperovich (timuralp@swiftstack.com) Tong Li (litong01@us.ibm.com) Tony Breeds (tony@bakeyournoodle.com) Tovin Seven (vinhnt@vn.fujitsu.com) Tristan Cacqueray (tristan.cacqueray@enovance.com) Vasyl Khomenko (vasiliyk@yahoo-inc.com) venkatamahesh (venkatamaheshkotha@gmail.com) Victor Stinner (victor.stinner@enovance.com) Vitaly Gridnev (vgridnev@mirantis.com) Vu Cong Tuan (tuanvc@vn.fujitsu.com) wangqi (wang.qi@99cloud.net) wangxiyuan (wangxiyuan@huawei.com) wangzhenyu (wangzy@fiberhome.com) Wu Wenxiang (wu.wenxiang@99cloud.net) wu.chunyang (wu.chunyang@99cloud.net) YangLei (yanglyy@cn.ibm.com) yangxurong (yangxurong@huawei.com) You Yamagata (bi.yamagata@gmail.com) Yuan Zhou (yuan.zhou@intel.com) Yushiro FURUKAWA (y.furukawa_2@jp.fujitsu.com) yuxcer (yuxcer@126.com) yuyafei (yu.yafei@zte.com.cn) YUZAWA Takahiko (yuzawataka@intellilink.co.jp) Zack M. Davis (zdavis@swiftstack.com) zhang-jinnan (ben.os@99cloud.net) zhangyanxian (zhangyanxianmail@163.com) zheng yin (yin.zheng@easystack.cn) Zhenguo Niu (zhenguo@unitedstack.com) ZhijunWei (wzj334965317@outlook.com) zhubx007 (zhu.boxiang@99cloud.net) ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/CONTRIBUTING.rst0000664000175000017500000000117400000000000020140 0ustar00zuulzuul00000000000000The source repository for this project can be found at: https://opendev.org/openstack/python-swiftclient Pull requests submitted through GitHub are not monitored. To start contributing to OpenStack, follow the steps in the contribution guide to set up and use Gerrit: https://docs.openstack.org/contributors/code-and-documentation/quick-start.html Bugs should be filed on Launchpad: https://bugs.launchpad.net/python-swiftclient For more specific information about contributing to this repository, see the swiftclient contributor guide: https://docs.openstack.org/python-swiftclient/latest/contributor/contributing.html ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/ChangeLog0000664000175000017500000005457100000000000017262 0ustar00zuulzuul000000000000003.9.0 ----- * Now tested under Python 3.8. * Better clean up connections when using the low-level client.py API. * Fixed a display issue when `swift delete` made multiple attempts to bulk delete objects. 3.8.1 ----- * Deleting or overwriting a symlink to an SLO or DLO will no longer attempt to clean up the large object's segments. * Fixed an issue sending non-ASCII metadata keys on Python 3. Note that receiving such metadata on py3 is still broken; see https://bugs.python.org/issue37093 * Documentation can now be rendered as a PDF. * Dropped Python 3.5 testing. 3.8.0 ----- * Added a new `--json` option to `swift list`. * Fixed an issue introduced in 3.5.0 where re-uploading an SLO with the same size, mtime, and segment size would delete all of the just-uploaded segments. * Various other minor bug fixes and improvements. 3.7.0 ----- * Added the delimiter keyword parameter to `get_account()` to match the functionality of `get_container()`. * Fixed an issue in the client module where socket connections weren't closed properly before being dereferenced. * Various other minor bug fixes and improvements. 3.6.0 ----- * Add the `--prompt` option for the CLI which will cause the user to be prompted to enter a password. Any password otherwise specified by `--key`, `--os-password` or an environment variable will be ignored. * Added bash completion support to the `swift` CLI. Enable this by sourcing the included `tools/swift.bash_completion` file. Make it permanent by including this file in the system's `/etc/bash_completion.d` directory. * Add ability to generate a temporary URL with an IP range restriction. TempURLs with IP restrictions are supported in Swift 2.19.0 or later. * The client.py SDK now supports a `query_string` option on the `head_object()` method. This is useful for finding information on SLO/DLO manifests without fetching the entire manifest. * The client.py SDK now respects `region_name` when using sessions. * Added a `.close()` method to an object response, allowing clients to give up on reading the rest of the response body, if they so choose. * Fixed a bug where using `--debug` in the CLI with unicode account names would cause a client crash. * Make OS_AUTH_URL work in DevStack (for testing) by default. * Dropped Python 3.4 testing. * Various other minor bug fixes and improvements. 3.5.0 ----- * Allow for object uploads > 5GB from stdin. When uploading from standard input, swiftclient will turn the upload into an SLO in the case of large objects. By default, input larger than 10MB will be uploaded as an SLO with 10MB segment sizes. Users can also supply the ``--segment-size`` option to alter that threshold and the SLO segment size. One segment is buffered in memory (which is why 10MB default was chosen). * The ``--meta`` option can now be set on the upload command. * Updated PyPy test dependency references to be more accurate on different distros. * Various other minor bug fixes and improvements. 3.4.0 ----- * The `swift` CLI now supports streaming from stdin. If "-" is given as the source, the object content is read from stdin. The `--object-name` must be given when content is loaded from stdin. * Tolerate RFC-compliant ETags returned from the server. * Skip checksum validation on partial downloads. * Buffer reads from disk, resulting in much faster upload throughput. * Added support for ISO 8601 timestamps for tempurl, matching the feature in Swift 2.13.0. * Added an option to ignore mtime metadata entry (`--ignore-mtime`). * When using SwiftService to delete many objects, the bulk delete page size will now be respected. Previously, exceeding this limit would prevent any objects from being deleted. * Expose `--prefix` as an option for st_delete. * Imported docs content from openstack-manuals project. * Various other minor bug fixes and improvements. 3.3.0 ----- * Added support for prefix-based tempurls. This allows you to create a tempurl that is valid for all objects which share a given prefix and matches the feature in Swift 2.12.0 and later. * In the SDK, we previously only accepted iterables of strings like 'Header: Value'. Now, we'll also accept lists of tuples like ('Header', 'Value') as well as dictionaries like {'Header': 'Value'}. * Improved help message strings * Various other minor bug fixes and improvements. 3.2.0 ----- * Added Keystone session support and a "v1password" plugin for Keystone. This plugin provides a way for Keystone sessions (and clients that use them, like python-openstackclient) to communicate with old auth endpoints that still use this mechanism. * HEAD, GET, and DELETE now support sending additional headers to match existing functionality on PUT requests. * Various other minor bug fixes and improvements. 3.1.0 ----- * Added a copy object method. * Arbitrary query strings can now be passed into container functions. * Client certificate and key can now be specified via CLI options (--os-cert/--os-key) or environment variables ($OS_CERT/$OS_KEY). * A new CLI option `--ignore-checksum` can be specified to turn off checksum validation. In the SDK, the new `checksum=True` parameter can be used for the same purpose. * Added --json option to `swift capabilities` / `swift info` * Default to v3 auth if we find a (user|project)-domain-(name|id) option. * Added a Python version constraint of >= Py27. * `client.py` will now retry on a 401 (auth error) even if `retries` is set to zero. * Fixed `swift download` when `marker` was specified. * Object segments uploaded via swiftclient are now given the content type "application/swiftclient-segment". * "Directory marker" objects are now given a "application/directory" content type to match both Swift's `staticweb` feature and other ecosystem tools. * Strip leading/trailing whitespace from headers (otherwise, new versions of the requests library will raise an InvalidHeader error). Additionally, header values with standard types (integer, float, or bool) are coerced to strings before being sent to a socket. * Non-python dependencies are now specified in bindep.txt. Currently this only lists a single dependency for testing (PyPy), but if future dependencies are added, they will be included in this file. * Client exceptions now include response headers. One benefit is that this allows clients to see transaction IDs without needing to turn on debug logging. * Client connections now accept gzip-encoded responses. * Various other minor bug fixes and improvements. 3.0.0 ----- * Python 2.6 and Python 3.3 support has been removed. Currently supported and tested versions of Python are Python 2.7 and Python 3.4. * Do not reveal sensitive headers in swiftclient log messages by default. This is controlled by the client.logger_settings dictionary. Setting the `redact_sensitive_headers` key to False prevents the information hiding. If the value is True (the default), the `reveal_sensitive_prefix` controls the maximum length of any sensitive header value logged. The default is 16 to match the default in Swift. * Object downloads that fail partway through will now retry with a Range request to read the rest of the object. * Object uploads will be retried if the source supports seek/tell or has a reset() method. * Delete requests will use the cluster's bulk delete feature, if available, for requests that would require a lot of individual deletes. * The delete CLI option now accepts a --prefix option to delete objects that start with the given prefix (similar to the same-named option for list). * Add support for the auth-version to be specified using --os-identity-api-version or OS_IDENTITY_API_VERSION for compatibility with other openstack client command line options. * --debug and --info command-line options now work anywhere in the command. * Objects can now be uploaded to pseudo-directories with the CLI. * Fixed an issue with uploading a large object that includes a unicode path. * swiftclient can now auth against Keystone using only a project (tenant) and a token. This is useful when the client doesn't have access to the password for a user but otherwise has been granted access. * Various other minor bug fixes and improvements. 2.7.0 ----- * This is the very last release to support Python 2.6. Any further development on the 2.7.x release series will only be for security bugfixes. * Added content type to CLI object list long-form output * client.get_container() and client.head_object now accept a headers parameter * Fixed bug when setting Content-Type on upload from CLI * Fixed bug when deleting DLOs with unicode characters * Updated man pages and docstrings * Suppress iso8601 logging in --debug output * Various other minor bug fixes and improvements. 2.6.0 ----- * Several CLI options have learned short options. The usage strings have been updated to reflect this. * Added --no-shuffle option to the CLI download command. * Added --absolute option for CLI TempURL generation and the corresponding parameter to utils.generate_temp_url(). This allows for an exact, specific time to be used for the TempURL expiry time. * CLI arguments are now always decoded as UTF-8. * Stop Connection class modifying os_options parameter. * Reduce memory usage for download/delete. * The swift service API now logs and reports the traceback on failed operations. * Increase httplib._MAXHEADERS to 256 to work around header limits in recent Python releases. * Added minimal working service token support to client.py. * Various other minor bug fixes and improvements. 2.5.0 ----- * The CLI learned an "auth" subcommand which returns bash environment snippets for auth credentials. * The CLI --version option is now more explicit by calling itself "python-swiftclient" rather than the name of the binary. * Now validates the checksum of each chunk of a large object as it is uploaded. * Fixes uploading an object with a relative path. * Added the ability to download objects to a particular folder. * Now correctly removes all old segments of an object when replacing a Dynamic Large Object (DLO). * The --skip-identical option now works properly when downloading large objects. * The client.get_object() response learned a .read([length]) method. * Fixed an issue where an intermediate caching/proxy service could cause object content to be improperly decoded. * Added a timeout parameter to HTTPConnection objects for socket-level read timeouts. * Removed a dependency on simplejson. * Various other minor bug fixes and improvements. 2.4.0 ----- * Mention --segment-size option after 413 response * Add improvements to MD5 validation * Unindent a chunk of st_list * Release connection after consuming the content * Verify MD5 of uploaded objects * Fix crash with -l, -d /, and pseudo folders * add functional tox target * Fix crash when stat'ing objects with non-ascii names * Add help message for " --help" * Fix missing ca-certificate parameter to get_auth * Fix deleting SLO segments on overwrite * This patch fixes downloading files to stdout * Fix environment sanitization for TestServiceUtils * Fix cross account upload using --os-storage-url * Change tests to use CaptureOutput class * Print info message about incorrect --totals usage when neither -l nor --lh is provided. Added test coverage for --totals * Make preauth params work * Fix misplaced check for None in SwiftUploadObject * Fix misnamed dictionary key * Change tests to use new CaptureOutput class * Workflow documentation is now in infra-manual * Show warning when auth_version >= 2 and keystoneclient is missing * Capture test output better * Suppress 'No handlers...' message from keystoneclient logger * Add unit tests for _encode_meta_headers * Fix misnamed variable in SwiftReader * Check that content_type header exists before using * Adds user friendly message when --segment-size is a non-integer * Make swift post output an error message when failing * Replaces Stacktraces with useful error messages * Fix KeyError raised from client Connection * Fix race in shell when testing for errors to raise SysExit * Fix race between container create jobs during upload * Fix the info command with --insecure * Allow segment size to be specified in a human readable way * Use skipTest from testtools instead of inherited Exception * Add tests for account listing using --lh switch * Do not crash with "swift list --lh" for Ceph RadosGW 2.3.1 ----- * Remove a debugging print statement * Fix unit tests failing when OS_ env vars are set * Fix bug with some OS options not being passed to client * Add per policy container count to account stat output * Stop creating extraneous directories 2.3.0 ----- * Work toward Python 3.4 support and testing * Add importable SwiftService incorporating shell.py logic * Adds console script entry point * Do not create an empty directory 'pseudo/' * fixed unit tests when env vars are set * Fix crash when downloading a pseudo-directory * Clean up raw policy stats in account stat * Update theme for docs * Add a tox job for generating docs * Add keystone v3 auth support 2.2.0 ----- * Fix context sensitive help for info and tempurl * Allow to specify storage policy when uploading objects * Adding Swift Temporary URL support * Add CONTRIBUTING.md * Add context sensitive help * Relax requirement for tenant_name in get_auth() * replace string format arguments with function parameters * Removed now unnecessary workaround for PyPy * Use Emacs-friendly coding line * Remove extra double quote from docstring * Fix wrong assertions in unit tests * fixed several pep8 issues 2.1.0 ----- * Fix Python3 bugs * Remove testtools.main() call from tests * Move test_shell.py under tests/unit/ * Mark swiftclient as being a universal wheel * change assert_ to assertTrue * change assertEquals to assertEqual * Provide a link to the documentation to the README * fixed typos found by RETF rules * Fix running the unittests under py3 * Add "." for help strings * Declare that we support Python 3 * Make the function tests Python3-import friendly * Only encode metadata for user customed headers * Add functional tests for python-swiftclient * Removed a duplicate word in a docstring * Mock auth_end_time in test_shell.test_download * Don't utf8 encode urls * Fixed several shell tests on Python3 * Fix up StringIO use in tests for py3 * Updated test_shell for Python3 * Fix test_raw_upload test * Remove validate_headers * Use quote/unquote from six module for py3 * Makes use of requests.Session * Fix test_multithreading on Python 3 * Add tests for bin/swift * Fix swiftclient.client.quote() for Python 3 * Add requests related unit-tests * Update help message to specify unit of --segment-size option * Python 3: fix tests on HTTP headers * Updated from global requirements * Use the standard library's copy of mock when it's available * Replaced print statements with print function * Removed usage of tuple unpacking in parameters * don't use mutable defaults in kwargs * set user-agent header * Python 3: Get compatible types from six * Python 3: Fix module names in import * Python 3: Add six dependency * Replace dict.iteritems() with dict.items() * Python 3: Replace iter.next() with six.next(iter) * Make bin/swift testable part 2 * Make bin/swift testable part 1 * Python 3: Fix tests using temporary text files * Python 3: cast map() result to list * Fix temporary pypy gate issue with setuptools * Decode HTTP responses, fixes bug #1282861 * Copy Swift's .mailmap to swiftclient repo * Improve help strings * TCP port is appended two time in ClientException * add "info" as an alias to "capabilities" * Use six.StringIO instead of StringIO.StringIO 2.0.3 ----- * Help string format persistent * Make the help strings constant * Add LengthWrapper in put_object to honor content_length param * Updated from global requirements * Remove useless statement * swift.1 manpage fix for groff warnings 2.0.2 ----- * Remove multipart/form-data file upload 2.0.1 ----- * Fix --insecure option on auth * Only run flake8 on swiftclient code 2.0 --- 1.9.0 ----- * Remove extraneous vim configuration comments * Rename Openstack to OpenStack * Port to python-requests * Add option to skip downloading/uploading identical files * Remove tox locale overrides * Fix swiftclient help * Fix misspellings in python swiftclient * changed things because reasons * Add missing backslash * match hacking rules in swift * Updated from global requirements * Install manpage in share/man/man1 instead of man/man1 * assertEquals is deprecated, use assertEqual * Add capabilities option * Install swiftclient manpage * Replace xrange in for loop with range * Add --object-name * retry on ratelimit * Fix help of some optional arguments * Updates tox.ini to use new features * Fix Sphinx version issue * Enable usage of proxies defined in environment (http(s)_proxy) * Don't crash when header is value of None * Fix download bandwidth for swift command * Updates .gitignore * Allow custom headers when using swift download (CLI) * Replaced two references to Cloud Files with Swift * Fix a typo in help text: "downlad" * Add close to swiftclient.client.Connection * enhance swiftclient logging * Clarify main help for post subcommand * Fixes python-swiftclient debugging message 1.8.0 ----- * Make pbr only a build-time dependency * Add verbose output to all stat commands * assertEquals is deprecated, use assertEqual (H602) * Skip sniffing and resetting if retry is disabled * user defined headers added to swift post queries 1.7.0 ----- * Sync with global requirements * fix bug with replace old *LOs * Extend usage message for `swift download` 1.6.0 ----- * Added support for running the tests under PyPy with tox * Remove redundant unit suffix * Reformat help outputs * Add a NullHandler when setting up library logging * Assignment to reserved built-in symbol "file" * Added headers argument support to get_object() * Move multi-threading code to a library * fix(gitignore) : Ignore *.egg files * python3: Start of adding basic python3 support * Added log statements in swift client * Update docstring for swiftclient.Connection.__init__ * Refuse carriage return in header value * Adds max-backoff for retries in Connection * Allow setting # of retries in the binary 1.5.0 ----- * Note '-V 2' is necessary for auth 2.0 * Allow storage url override for both auth vers * Add *.swp into .gitignore * Add -p option to download command * add -t for totals to list command and --lh to stat * add optional 'response_dict' parameters to many calls into which they'll return a dictionary of the response status, reason and headers * Fixes re-auth flow with expired tokens * Remove explicit distribute depend * Add -l and --lh switches to swift 'list' command * Changed the call to set_tunnel to work in python 2.6 or python 2.7 since its name changed between versions * Add option to disable SSL compression * python3: Introduce py33 to tox.ini * Rename requires files to standard names * remove busy-wait so that swift client won't use up all CPU cycles * log get_auth request url instead of x-storage-url * Update the man page * Add .coveragerc file to show correct code coverage * do not warn about etag for slo * Eradicate eventlet and fix bug lp:959221 * Add end_marker and path query parameters * Switch to pbr for setup * Switch to flake8 * Improve Python 3.x compatibility * Confirm we have auth creds before clearing preauth 1.4.0 ----- * Improve auth option help * Static large object support * Fixed pep8 errors in test directory * Allow user to specify headers at the command line * Enhance put_object to inform when chunk is ignored * Allow v2 to use storage_url/storage_token directly * Add client man page swift.1 * Allow to specify segment container * Added "/" check when list containers * Print useful message when keystoneclient is not installed * Fix reporting version 1.3.0 ----- * Use testr instead of nose * Update to latest oslo version/setup * Add generated files to .gitignore * Add env[SWIFTCLIENT_INSECURE] * Fix debug feature and add --debug to swift * Use testtools as base class for test cases * Add --os-cacert * Add --insecure option to fix bug #1077869 * Don't segment objects smaller than --segment-size * Don't add trailing slash to auth URL * Adding segment size as another x-object-manifest component * Stop loss of precision when writing 'x-object-meta-mtime' * Remove unused json_request * fixed inconsistencies in parameter descriptions * tell nose to explicity test the 'tests' directory * Fixes setup compatibility issue on Windows * Force utf-8 encode of HTTPConnection params * swiftclient Connection : default optional arguments to None * Add OpenStack trove classifier for PyPI * Resolves issue with empty os_options for swift-bench & swift-dispersion-report * Catch authorization failures * Do not use dictionaries as default parameters 1.2.0 ----- * Add region_name support * Allow endpoint type to be specified * PEP8 cleanup * PEP8 issues fixed * Add ability to download without writing to disk * Fix PEP8 issues * Change '_' to '-' in options * Fix swiftclient 400 error when OS_AUTH_URL is set * Add nosehtmloutput as a test dependency * Shuffle download order (of containers and objects) * Add timing stats to verbose download output * Ensure Content-Length header when PUT/POST a container * Make python-keystoneclient optional * Fix container delete throughput and 409 retries * Consume version info from pkg_resources * Use keystoneclient for authentication * Removes the title "Swift Web" from landing page 1.1.1 ----- * Now url encodes/decodes x-object-manifest values * Configurable concurrency for swift client * Allow specify tenant:user in user * Make swift exit on ctrl-c * Add post-tag versioning * Don't suppress openstack auth options * Make swift not hang on error * Fix pep8 errors w/pep8==1.3 * Add missing test/tools files to the tarball * Add build_sphinx options * Make CLI exit nonzero on error * Add doc and version in swiftclient.__init__.py * Raise ClientException for invalid auth version * Version bump after pypi release 1.1.0 ----- * Removed now-unused .cache.bundle references * Added setup.cfg for verbose test output * Add run_tests.sh script here * Adding fake_http_connect to test.utils * Add openstack project infrastructure * Add logging * Defined version to 1.0 * Add CHANGELOG LICENSE and MANIFEST.in * Delete old test_client and add a gitignore * Rename client to swiftclient * Fix links * Import script from swift to run unittests * Add test_client from original swift repository * Add AUTHORS file * Make sure we get a header StorageURL with 1.0 * Allow specify the tenant in user * First commit ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/LICENSE0000664000175000017500000002363600000000000016513 0ustar00zuulzuul00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/MANIFEST.in0000664000175000017500000000025600000000000017235 0ustar00zuulzuul00000000000000include AUTHORS include ChangeLog include LICENSE include README.rst include run_tests.sh tox.ini recursive-include doc * recursive-include tests * recursive-include tools * ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.1096733 python-swiftclient-3.13.1/PKG-INFO0000664000175000017500000000620100000000000016570 0ustar00zuulzuul00000000000000Metadata-Version: 2.1 Name: python-swiftclient Version: 3.13.1 Summary: OpenStack Object Storage API Client Library Home-page: https://docs.openstack.org/python-swiftclient/latest/ Author: OpenStack Author-email: openstack-discuss@lists.openstack.org License: UNKNOWN Description: ======================== Team and repository tags ======================== .. image:: https://governance.openstack.org/tc/badges/python-swiftclient.svg :target: https://governance.openstack.org/tc/reference/tags/index.html .. Change things from this point on Python bindings to the OpenStack Object Storage API =================================================== .. image:: https://img.shields.io/pypi/v/python-swiftclient.svg :target: https://pypi.org/project/python-swiftclient/ :alt: Latest Version This is a python client for the Swift API. There's a Python API (the ``swiftclient`` module), and a command-line script (``swift``). Development takes place via the usual OpenStack processes as outlined in the `OpenStack wiki`__. __ https://docs.openstack.org/infra/manual/developers.html This code is based on the original client previously included with `OpenStack's Swift`__. The python-swiftclient is licensed under the Apache License like the rest of OpenStack. __ https://github.com/openstack/swift * Free software: Apache license * `PyPI`_ - package installation * `Online Documentation`_ * `Launchpad project`_ - release management * `Bugs`_ - issue tracking * `Source`_ * `How to Contribute`_ * `Release Notes`_ .. _PyPI: https://pypi.org/project/python-swiftclient .. _Online Documentation: https://docs.openstack.org/python-swiftclient/latest/ .. _Launchpad project: https://launchpad.net/python-swiftclient .. _Bugs: https://bugs.launchpad.net/python-swiftclient .. _Source: https://opendev.org/openstack/python-swiftclient .. _How to Contribute: https://docs.openstack.org/infra/manual/developers.html .. _Release Notes: https://docs.openstack.org/releasenotes/python-swiftclient .. contents:: Contents: :local: Platform: UNKNOWN Classifier: Environment :: OpenStack Classifier: Intended Audience :: Information Technology Classifier: Intended Audience :: System Administrators Classifier: License :: OSI Approved :: Apache Software License Classifier: Operating System :: POSIX :: Linux Classifier: Operating System :: Microsoft :: Windows Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.6 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Classifier: Programming Language :: Python :: 3.9 Provides-Extra: keystone Provides-Extra: test ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/README.rst0000664000175000017500000000333200000000000017164 0ustar00zuulzuul00000000000000======================== Team and repository tags ======================== .. image:: https://governance.openstack.org/tc/badges/python-swiftclient.svg :target: https://governance.openstack.org/tc/reference/tags/index.html .. Change things from this point on Python bindings to the OpenStack Object Storage API =================================================== .. image:: https://img.shields.io/pypi/v/python-swiftclient.svg :target: https://pypi.org/project/python-swiftclient/ :alt: Latest Version This is a python client for the Swift API. There's a Python API (the ``swiftclient`` module), and a command-line script (``swift``). Development takes place via the usual OpenStack processes as outlined in the `OpenStack wiki`__. __ https://docs.openstack.org/infra/manual/developers.html This code is based on the original client previously included with `OpenStack's Swift`__. The python-swiftclient is licensed under the Apache License like the rest of OpenStack. __ https://github.com/openstack/swift * Free software: Apache license * `PyPI`_ - package installation * `Online Documentation`_ * `Launchpad project`_ - release management * `Bugs`_ - issue tracking * `Source`_ * `How to Contribute`_ * `Release Notes`_ .. _PyPI: https://pypi.org/project/python-swiftclient .. _Online Documentation: https://docs.openstack.org/python-swiftclient/latest/ .. _Launchpad project: https://launchpad.net/python-swiftclient .. _Bugs: https://bugs.launchpad.net/python-swiftclient .. _Source: https://opendev.org/openstack/python-swiftclient .. _How to Contribute: https://docs.openstack.org/infra/manual/developers.html .. _Release Notes: https://docs.openstack.org/releasenotes/python-swiftclient .. contents:: Contents: :local: ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/bin/0000775000175000017500000000000000000000000016244 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/bin/swift0000775000175000017500000000134000000000000017324 0ustar00zuulzuul00000000000000#!/usr/bin/python # Copyright (c) 2014 Christian Schwede # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or # implied. # See the License for the specific language governing permissions and # limitations under the License. import sys from swiftclient.shell import main if __name__ == "__main__": sys.exit(main()) ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/bindep.txt0000664000175000017500000000040700000000000017477 0ustar00zuulzuul00000000000000# This is a cross-platform list tracking distribution packages needed by tests; # see https://docs.openstack.org/infra/bindep/ for additional information. pypy [test !platform:fedora] pypy-dev [test platform:dpkg] pypy-devel [test platform:rpm !platform:fedora] ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/doc/0000775000175000017500000000000000000000000016241 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/Makefile0000664000175000017500000000616200000000000017706 0ustar00zuulzuul00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXSOURCE = source PAPER = BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE) .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " pickle to make pickle files" @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: -rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-swiftclient.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-swiftclient.qhc" latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ "run these through (pdf)latex." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/doc/manpages/0000775000175000017500000000000000000000000020034 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/manpages/swift.10000664000175000017500000002156100000000000021257 0ustar00zuulzuul00000000000000.\" .\" Author: Joao Marcelo Martins or .\" Copyright (c) 2010-2011 OpenStack Foundation. .\" .\" Licensed under the Apache License, Version 2.0 (the "License"); .\" you may not use this file except in compliance with the License. .\" You may obtain a copy of the License at .\" .\" http://www.apache.org/licenses/LICENSE-2.0 .\" .\" Unless required by applicable law or agreed to in writing, software .\" distributed under the License is distributed on an "AS IS" BASIS, .\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or .\" implied. .\" See the License for the specific language governing permissions and .\" limitations under the License. .\" .TH swift 1 "8/26/2011" "Linux" "OpenStack Swift" .SH NAME .LP .B swift \- OpenStack Swift client tool .SH SYNOPSIS .LP .B swift [options] [args] .SH DESCRIPTION .PP The \fBswift\fR tool is a command line utility for communicating with an OpenStack Object Storage (Swift) environment. It allows one to perform several types of operations. .SH COMMANDS .PP \fBstat\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] .RS 4 Displays information for the account, container, or object depending on the args given (if any). In verbose mode, the Storage URL and the authentication token are displayed as well. Option \-\-lh reports sizes in human readable format similar to ls \-lh. .RE \fBlist\fR [\fIcommand-options\fR] [\fIcontainer\fR] .RS 4 Lists the containers for the account or the objects for a container. The \-p or \-\-prefix is an option that will only list items beginning with that prefix. The \-d or \-\-delimiter is option (for container listings only) that will roll up items with the given delimiter (see OpenStack Swift general documentation for what this means). The \-l or \-\-long and \-\-lh options provide more detail, similar to ls \-l and ls \-lh, the latter providing sizes in human readable format (eg 3K, 12M, etc). These latter 2 switches use more overhead to get those details, which is directly proportional to the number of container or objects being listed. With the \-t or \-\-total option they only report totals. .RE \fBupload\fR [\fIcommand-options\fR] container file_or_directory [\fIfile_or_directory\fR] [...] .RS 4 Uploads to the given container the files and directories specified by the remaining args. The \-c or \-\-changed is an option that will only upload files that have changed since the last upload. The \-\-object\-name is an option that will upload file and name object to or upload dir and use as object prefix. If the file name is "-", reads the content from standard input. In this case, \-\-object\-name is required and no other files may be given. The \-S or \-\-segment\-size and \-\-leave\-segments and others are options as well (see swift upload \-\-help for more). .RE \fBpost\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] .RS 4 Updates meta information for the account, container, or object depending on the args given. If the container is not found, it will be created automatically; but this is not true for accounts and objects. Containers also allow the \-r (or \-\-read\-acl) and \-w (or \-\-write\-acl) options. The \-m or \-\-meta option is allowed on all and used to define the user meta data items to set in the form Name:Value. This option can be repeated. For more details and options see swift post \-\-help. \fBExample\fR: post \-m Color:Blue \-m Size:Large .RE \fBcopy\fR [\fIcommand-options\fR] \fIcontainer\fR \fIobject\fR .RS 4 Copies an object to a new destination or adds user metadata to the object (current user metadata will be preserved, in contrast with the post command) depending on the args given. The \-\-destination option sets the destination in the form /container/object. If not set, the object will be copied onto itself which is useful for adding metadata. The \-M or \-\-fresh\-metadata option copies the object without the existing user metadata. The \-m or \-\-meta option is always allowed and is used to define the user metadata items to set in the form Name:Value (this option can be repeated). For more details and options see swift copy \-\-help. .RE \fBdownload\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...] .RS 4 Downloads everything in the account (with \-\-all), or everything in a container, or a list of objects depending on the args given. For a single object download, you may use the \-o [\-\-output] option to redirect the output to a specific file or if "-" then just redirect to stdout or with \-\-no-download actually not to write anything to disk. The \-\-ignore-checksum is an option that turns off checksum validation. You can specify optional headers with the repeatable cURL-like option \-H [\-\-header]. For more details and options see swift download \-\-help. The \-\-ignore\-mtime option ignores the x\-object\-meta\-mtime metadata entry on the object (if present) and instead creates the downloaded files with fresh atime and mtime values. .RE \fBdelete\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...] .RS 4 Deletes everything in the account (with \-\-all), or everything in a container, or all objects in a container that start with a given string (given by \-\-prefix), or a list of objects depending on the args given. Segments of manifest objects will be deleted as well, unless you specify the \-\-leave\-segments option. For more details and options see swift delete \-\-help. .RE \fBcapabilities\fR [\fIcommand-options\fR] [\fIproxy-url\fR] .RS 4 Displays cluster capabilities. If the proxy-url option is not provided the storage-url retrieved after authentication is used as proxy-url. By default, the output includes the list of the activated Swift middlewares as well as relevant options for each one. Additionally the command displays relevant options for the Swift core. The \-\-json option will print a json representation of the cluster capabilities. This is typically more suitable for consumption by other programs, such as jq. \fBExample\fR: capabilities https://swift.example.com capabilities \-\-json .RE \fBtempurl\fR [\fIcommand-option\fR] \fImethod\fR \fItime\fR \fIpath\fR \fIkey\fR .RS 4 Generates a temporary URL allowing unauthenticated access to the Swift object at the given path, using the given HTTP method, for the given time, using the given TempURL key. The time can be specified either as an integer denoting the amount of seconds the temporary URL is valid, or as an ISO 8601 timestamp in one of following formats: Complete date: YYYY\-MM\-DD (eg 1997\-07\-16), complete date plus hours, minutes and seconds: YYYY\-MM\-DDThh:mm:ss (eg 1997\-07\-16T19:20:30) or complete date plus hours, minutes and seconds with UTC designator: YYYY\-MM\-DDThh:mm:ssZ (eg 1997\-07\-16T19:20:30Z). Be aware that if you do not use the latter format, the timestamp is generated using your locale timezone. If the first format is used, the time part used will equal to 00:00:00. With the \-\-prefix\-based option a prefix-based URL is generated. The option \-\-iso8601 provides ISO 8601 UTC timestamps instead of Unix timestamps inside the generated URL. If optional \-\-absolute argument is provided and the time argument is specified in seconds, the seconds are interpreted as a Unix timestamp at which the URL should expire. \fBExample\fR: tempurl GET $(date \-d "Jan 1 2016" +%s) /v1/AUTH_foo/bar_container/quux.md my_secret_tempurl_key \-\-absolute .RE \fBauth\fR .RS 4 Display auth related authentication variables in shell friendly format. For examples see swift auth \-\-help. .RE .SH OPTIONS .PD 0 .IP "--version Show program's version number and exit" .IP "-h, --help Show this (or any subcommand if after command) help message and exit" .IP "-s, --snet Use SERVICENET internal network" .IP "-v, --verbose Print more info" .IP "-q, --quiet Suppress status output" .IP "-A AUTH, --auth=AUTH URL for obtaining an auth token " .IP "-U USER, --user=USER User name for obtaining an auth token" .IP "-V 1|2, --auth-version=VERSION Authentication protocol version" .IP "-K KEY, --key=KEY Key for obtaining an auth token" .IP "--os-storage-url=URL Use this instead of URL returned from auth" .IP "--os-help Show all OpenStack authentication options" .PD .RS 4 For more options see swift \-\-help and swift \-\-os\-help. .RE .SH EXAMPLE .PP swift \-A https://127.0.0.1:443/auth/v1.0 \-U swiftops:swiftops \-K swiftops stat .RS 2 .PD 0 .IP " Account: AUTH_43b42dae-dc0b-4a4b-ac55-97de614d6e6e" .IP "Containers: 1" .IP " Objects: 1" .IP " Bytes: 1124" .IP "Accept-Ranges: bytes" .IP "X-Trans-Id: txb21186a9eef64ed295a1e95896a0fc72" .PD .RE .SH DOCUMENTATION .LP More in depth documentation about OpenStack Swift as a whole can be found at .BI https://docs.openstack.org/swift/latest/ ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/requirements.txt0000664000175000017500000000023000000000000021520 0ustar00zuulzuul00000000000000keystoneauth1>=3.4.0 # Apache-2.0 sphinx>=1.6.2,!=1.6.6,!=1.6.7,!=2.1.0,!=3.0.0 # BSD reno>=3.1.0 # Apache-2.0 openstackdocstheme>=2.2.1 # Apache-2.0 ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/doc/source/0000775000175000017500000000000000000000000017541 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/doc/source/_static/0000775000175000017500000000000000000000000021167 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/_static/.gitignore0000664000175000017500000000000000000000000023145 0ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/doc/source/_templates/0000775000175000017500000000000000000000000021676 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/_templates/.empty0000664000175000017500000000000000000000000023023 0ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/doc/source/cli/0000775000175000017500000000000000000000000020310 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/cli/index.rst0000664000175000017500000007102200000000000022153 0ustar00zuulzuul00000000000000==== CLI ==== The ``swift`` tool is a command line utility for communicating with an OpenStack Object Storage (swift) environment. It allows one to perform several types of operations. For help on a specific :command:`swift` command, enter: .. code-block:: console $ swift COMMAND --help .. _swift_command_usage: swift usage ~~~~~~~~~~~ .. code-block:: console Usage: swift [--version] [--help] [--os-help] [--snet] [--verbose] [--debug] [--info] [--quiet] [--auth ] [--auth-version | --os-identity-api-version ] [--user ] [--key ] [--retries ] [--os-username ] [--os-password ] [--os-user-id ] [--os-user-domain-id ] [--os-user-domain-name ] [--os-tenant-id ] [--os-tenant-name ] [--os-project-id ] [--os-project-name ] [--os-project-domain-id ] [--os-project-domain-name ] [--os-auth-url ] [--os-auth-token ] [--os-storage-url ] [--os-region-name ] [--os-service-type ] [--os-endpoint-type ] [--os-cacert ] [--insecure] [--os-cert ] [--os-key ] [--no-ssl-compression] [--help] [] **Subcommands:** ``delete`` Delete a container or objects within a container. ``download`` Download objects from containers. ``list`` Lists the containers for the account or the objects for a container. ``post`` Updates meta information for the account, container, or object; creates containers if not present. ``copy`` Copies object, optionally adds meta ``stat`` Displays information for the account, container, or object. ``upload`` Uploads files or directories to the given container. ``capabilities`` List cluster capabilities. ``tempurl`` Create a temporary URL. ``auth`` Display auth related environment variables. .. _swift_command_options: swift optional arguments ~~~~~~~~~~~~~~~~~~~~~~~~ ``--version`` show program's version number and exit ``-h, --help`` show this help message and exit ``--os-help`` Show OpenStack authentication options. ``-s, --snet`` Use SERVICENET internal network. ``-v, --verbose`` Print more info. ``--debug`` Show the curl commands and results of all http queries regardless of result status. ``--info`` Show the curl commands and results of all http queries which return an error. ``-q, --quiet`` Suppress status output. ``-A AUTH, --auth=AUTH`` URL for obtaining an auth token. ``-V AUTH_VERSION, --auth-version=AUTH_VERSION, --os-identity-api-version=AUTH_VERSION`` Specify a version for authentication. Defaults to ``env[ST_AUTH_VERSION]``, ``env[OS_AUTH_VERSION]``, ``env[OS_IDENTITY_API_VERSION]`` or 1.0. ``-U USER, --user=USER`` User name for obtaining an auth token. ``-K KEY, --key=KEY`` Key for obtaining an auth token. ``-R RETRIES, --retries=RETRIES`` The number of times to retry a failed connection. ``--insecure`` Allow swiftclient to access servers without having to verify the SSL certificate. Defaults to ``env[SWIFTCLIENT_INSECURE]`` (set to 'true' to enable). ``--no-ssl-compression`` This option is deprecated and not used anymore. SSL compression should be disabled by default by the system SSL library. ``--prompt`` Prompt user to enter a password which overrides any password supplied via ``--key``, ``--os-password`` or environment variables. Authentication ~~~~~~~~~~~~~~ This section covers the options for authenticating with a swift object store. The combinations of options required for each authentication version are detailed below, but are just a subset of those that can be used to successfully authenticate. These are the most common and recommended combinations. You should obtain the details of your authentication version and credentials from your storage provider. These details should make it clearer which of the authentication sections below are most likely to allow you to connect to your storage account. Keystone v3 ----------- .. code-block:: bash swift --os-auth-url https://api.example.com:5000/v3 --auth-version 3 \ --os-project-name project1 --os-project-domain-name domain1 \ --os-username user --os-user-domain-name domain1 \ --os-password password list swift --os-auth-url https://api.example.com:5000/v3 --auth-version 3 \ --os-project-id 0123456789abcdef0123456789abcdef \ --os-user-id abcdef0123456789abcdef0123456789 \ --os-password password list Manually specifying the options above on the command line can be avoided by setting the following combinations of environment variables: .. code-block:: bash ST_AUTH_VERSION=3 OS_USERNAME=user OS_USER_DOMAIN_NAME=domain1 OS_PASSWORD=password OS_PROJECT_NAME=project1 OS_PROJECT_DOMAIN_NAME=domain1 OS_AUTH_URL=https://api.example.com:5000/v3 ST_AUTH_VERSION=3 OS_USER_ID=abcdef0123456789abcdef0123456789 OS_PASSWORD=password OS_PROJECT_ID=0123456789abcdef0123456789abcdef OS_AUTH_URL=https://api.example.com:5000/v3 Keystone v2 ----------- .. code-block:: bash swift --os-auth-url https://api.example.com:5000/v2.0 \ --os-tenant-name tenant \ --os-username user --os-password password list Manually specifying the options above on the command line can be avoided by setting the following environment variables: .. code-block:: bash ST_AUTH_VERSION=2.0 OS_USERNAME=user OS_PASSWORD=password OS_TENANT_NAME=tenant OS_AUTH_URL=https://api.example.com:5000/v2.0 Legacy auth systems ------------------- You can configure swift to work with any number of other authentication systems that we will not cover in this document. If your storage provider is not using Keystone to provide access tokens, please contact them for instructions on the required options. It is likely that the options will need to be specified as below: .. code-block:: bash swift -A https://api.example.com/v1.0 -U user -K api_key list Specifying the options above manually on the command line can be avoided by setting the following environment variables: .. code-block:: bash ST_AUTH_VERSION=1.0 ST_AUTH=https://api.example.com/v1.0 ST_USER=user ST_KEY=key It is also possible that you need to use a completely separate auth system, in which case ``swiftclient`` cannot request a token for you. In this case you should make the authentication request separately and access your storage using the token and storage URL options shown below: .. code-block:: bash swift --os-auth-token 6ee5eb33efad4e45ab46806eac010566 \ --os-storage-url https://10.1.5.2:8080/v1/AUTH_ced809b6a4baea7aeab61a \ list .. note:: Leftover environment variables are a common source of confusion when authorization fails. CLI commands ~~~~~~~~~~~~ .. _swift_auth: Auth ---- .. code-block:: console Usage: swift auth Display authentication variables in shell friendly format. Command to run to export storage URL and auth token into ``OS_STORAGE_URL`` and ``OS_AUTH_TOKEN``: ``swift auth``. Command to append to a runcom file (e.g. ``~/.bashrc``, ``/etc/profile``) for automatic authentication: ``swift auth -v -U test:tester -K testing``. .. _swift_stat: swift stat ---------- .. code-block:: console Usage: swift stat [--lh] [--header ] [ []] Displays information for the account, container, or object depending on the arguments given (if any). In verbose mode, the storage URL and the authentication token are displayed as well. **Positional arguments:** ``[container]`` Name of container to stat from. ``[object]`` Name of object to stat. **Optional arguments:** ``--lh`` Report sizes in human readable format similar to ls -lh. ``-H, --header `` Adds a custom request header to use for stat. .. _swift_list: swift list ---------- .. code-block:: console Usage: swift list [--long] [--lh] [--totals] [--prefix ] [--delimiter ] [--header ] [] Lists the containers for the account or the objects for a container. The ``-p `` or ``--prefix `` is an option that will only list items beginning with that prefix. The ``-d `` or ``--delimiter `` is an option (for container listings only) that will roll up items with the given delimiter (see `OpenStack Swift general documentation ` for what this means). The ``-l`` and ``--lh`` options provide more detail, similar to ``ls -l`` and ``ls -lh``, the latter providing sizes in human readable format (For example: ``3K``, ``12M``, etc). The latter two switches use more overhead to retrieve the displayed details, which is directly proportional to the number of container or objects listed. **Positional arguments:** ``[container]`` Name of container to list object in. **Optional arguments:** ``-l, --long`` Long listing format, similar to ls -l. ``--lh`` Report sizes in human readable format similar to ls -lh. ``-t, --totals`` Used with -l or --lh, only report totals. ``-p , --prefix `` Only list items beginning with the prefix. ``-d , --delimiter `` Roll up items with the given delimiter. For containers only. See OpenStack Swift API documentation for what this means. ``-H, --header `` Adds a custom request header to use for listing. .. _swift_upload: swift upload ------------ .. code-block:: console Usage: swift upload [--changed] [--skip-identical] [--segment-size ] [--segment-container ] [--leave-segments] [--object-threads ] [--segment-threads ] [--header
] [--use-slo] [--ignore-checksum] [--object-name ] [] [...] Uploads the files and directories specified by the remaining arguments to the given container. The ``-c`` or ``--changed`` is an option that will only upload files that have changed since the last upload. The ``--object-name `` is an option that will upload a file and name object to ```` or upload a directory and use ```` as object prefix. If the file name is "-", client reads content from standard input. In this case ``--object-name`` is required to set the name of the object and no other files may be given. The ``-S `` or ``--segment-size `` and ``--leave-segments`` are options as well (see ``--help`` for more). **Positional arguments:** ```` Name of container to upload to. ```` Name of file or directory to upload. Specify multiple times for multiple uploads. **Optional arguments:** ``-c, --changed`` Only upload files that have changed since the last upload. ``--skip-identical`` Skip uploading files that are identical on both sides. ``-S, --segment-size `` Upload files in segments no larger than (in Bytes) and then create a "manifest" file that will download all the segments as if it were the original file. ``--segment-container `` Upload the segments into the specified container. If not specified, the segments will be uploaded to a _segments container to not pollute the main listings. ``--leave-segments`` Indicates that you want the older segments of manifest objects left alone (in the case of overwrites). ``--object-threads `` Number of threads to use for uploading full objects. Default is 10. ``--segment-threads `` Number of threads to use for uploading object segments. Default is 10. ``-H, --header `` Adds a customized request header. This option may be repeated. Example: -H "content-type:text/plain" -H "Content-Length: 4000". ``--use-slo`` When used in conjunction with --segment-size it will create a Static Large Object instead of the default Dynamic Large Object. ``--object-name `` Upload file and name object to or upload dir and use as object prefix instead of folder name. ``--ignore-checksum`` Turn off checksum validation for uploads. .. _swift_post: swift post ---------- .. code-block:: console Usage: swift post [--read-acl ] [--write-acl ] [--sync-to ] [--sync-key ] [--meta ] [--header
] [ []] Updates meta information for the account, container, or object depending on the arguments given. If the container is not found, the ``swiftclient`` will create it automatically, but this is not true for accounts and objects. Containers also allow the ``-r `` (or ``--read-acl ``) and ``-w `` (or ``--write-acl ``) options. The ``-m`` or ``--meta`` option is allowed on accounts, containers and objects, and is used to define the user metadata items to set in the form ``Name:Value``. You can repeat this option. For example: ``post -m Color:Blue -m Size:Large`` For more information about ACL formats see the documentation: `ACLs `_. **Positional arguments:** ``[container]`` Name of container to post to. ``[object]`` Name of object to post. **Optional arguments:** ``-r, --read-acl `` Read ACL for containers. Quick summary of ACL syntax: ``.r:*``, ``.r:-.example.com``, ``.r:www.example.com``, ``account1`` (v1.0 identity API only), ``account1:*``, ``account2:user2`` (v2.0+ identity API). ``-w, --write-acl `` Write ACL for containers. Quick summary of ACL syntax: ``account1`` (v1.0 identity API only), ``account1:*``, ``account2:user2`` (v2.0+ identity API). ``-t, --sync-to `` Sync To for containers, for multi-cluster replication. ``-k, --sync-key `` Sync Key for containers, for multi-cluster replication. ``-m, --meta `` Sets a meta data item. This option may be repeated. Example: -m Color:Blue -m Size:Large ``-H, --header `` Adds a customized request header. This option may be repeated. Example: -H "content-type:text/plain" -H "Content-Length: 4000" .. _swift_download: swift download -------------- .. code-block:: console Usage: swift download [--all] [--marker ] [--prefix ] [--output ] [--output-dir ] [--object-threads ] [--ignore-checksum] [--container-threads ] [--no-download] [--skip-identical] [--remove-prefix] [--header ] [--no-shuffle] [ [] [...]] Downloads everything in the account (with ``--all``), or everything in a container, or a list of objects depending on the arguments given. For a single object download, you may use the ``-o `` or ``--output `` option to redirect the output to a specific file or ``-`` to redirect to stdout. The ``--ignore-checksum`` is an option that turn off checksum validation. You can specify optional headers with the repeatable cURL-like option ``-H [--header ]``. ``--ignore-mtime`` ignores the ``x-object-meta-mtime`` metadata entry on the object (if present) and instead creates the downloaded files with fresh atime and mtime values. **Positional arguments:** ```` Name of container to download from. To download a whole account, omit this and specify --all. ```` Name of object to download. Specify multiple times for multiple objects. Omit this to download all objects from the container. **Optional arguments:** ``-a, --all`` Indicates that you really want to download everything in the account. ``-m, --marker `` Marker to use when starting a container or account download. ``-p, --prefix `` Only download items beginning with ``-r, --remove-prefix`` An optional flag for --prefix , use this option to download items without ``-o, --output `` For a single file download, stream the output to . Specifying "-" as will redirect to stdout. ``-D, --output-dir `` An optional directory to which to store objects. By default, all objects are recreated in the current directory. ``--object-threads `` Number of threads to use for downloading objects. Default is 10. ``--container-threads `` Number of threads to use for downloading containers. Default is 10. ``--no-download`` Perform download(s), but don't actually write anything to disk. ``-H, --header `` Adds a customized request header to the query, like "Range" or "If-Match". This option may be repeated. Example: --header "content-type:text/plain" ``--skip-identical`` Skip downloading files that are identical on both sides. ``--ignore-checksum`` Turn off checksum validation for downloads. ``--no-shuffle`` By default, when downloading a complete account or container, download order is randomised in order to reduce the load on individual drives when multiple clients are executed simultaneously to download the same set of objects (e.g. a nightly automated download script to multiple servers). Enable this option to submit download jobs to the thread pool in the order they are listed in the object store. .. _swift_delete: swift delete ------------ .. code-block:: console Usage: swift delete [--all] [--leave-segments] [--object-threads ] [--container-threads ] [--header ] [ [] [...]] Deletes everything in the account (with ``--all``), or everything in a container, or a list of objects depending on the arguments given. Segments of manifest objects will be deleted as well, unless you specify the ``--leave-segments`` option. **Positional arguments:** ``[]`` Name of container to delete from. ``[]`` Name of object to delete. Specify multiple times for multiple objects. **Optional arguments:** ``-a, --all`` Delete all containers and objects. ``--leave-segments`` Do not delete segments of manifest objects. ``-H, --header `` Adds a custom request header to use for deleting objects or an entire container. ``--object-threads `` Number of threads to use for deleting objects. Default is 10. ``--container-threads `` Number of threads to use for deleting containers. Default is 10. .. _swift_copy: swift copy ---------- .. code-block:: console Usage: swift copy [--destination ] [--fresh-metadata] [--meta ] [--header
] [] [...] Copies an object to a new destination or adds user metadata to an object. Depending on the options supplied, you can preserve existing metadata in contrast to the post command. The ``--destination`` option sets the copy target destination in the form ``/container/object``. If not set, the object will be copied onto itself which is useful for adding metadata. You can use the ``-M`` or ``--fresh-metadata`` option to copy an object without existing user meta data, and the ``-m`` or ``--meta`` option to define user meta data items to set in the form ``Name:Value``. You can repeat this option. For example: ``copy -m Color:Blue -m Size:Large``. **Positional arguments:** ```` Name of container to copy from. ```` Name of object to copy. Specify multiple times for multiple objects **Optional arguments:** ``-d, --destination `` The container and name of the destination object. Name of destination object can be omitted, then will be same as name of source object. Supplying multiple objects and destination with object name is invalid. ``-M, --fresh-metadata`` Copy the object without any existing metadata, If not set, metadata will be preserved or appended ``-m, --meta `` Sets a meta data item. This option may be repeated. Example: -m Color:Blue -m Size:Large ``-H, --header `` Adds a customized request header. This option may be repeated. Example: -H "content-type:text/plain" -H "Content-Length: 4000" .. _swift_capabilities: swift capabilities ------------------ .. code-block:: console Usage: swift capabilities [--json] [] Displays cluster capabilities. The output includes the list of the activated Swift middlewares as well as relevant options for each ones. Additionally the command displays relevant options for the Swift core. If the ``proxy-url`` option is not provided, the storage URL retrieved after authentication is used as ``proxy-url``. **Optional positional arguments:** ```` Proxy URL of the cluster to retrieve capabilities. ``--json`` Print the cluster capabilities in JSON format. .. _swift_tempurl: swift tempurl ------------- .. code-block:: console Usage: swift tempurl [--absolute] [--prefix-based] Generates a temporary URL for a Swift object. ``method`` option sets an HTTP method to allow for this temporary URL that is usually ``GET`` or ``PUT``. ``time`` option sets the amount of time the temporary URL will be valid for. ``time`` can be specified as an integer, denoting the number of seconds from now on until the URL shall be valid; or, if ``--absolute`` is passed, the Unix timestamp when the temporary URL will expire. But beyond that, ``time`` can also be specified as an ISO 8601 timestamp in one of following formats: i) Complete date: YYYY-MM-DD (e.g. 1997-07-16) ii) Complete date plus hours, minutes and seconds: YYYY-MM-DDThh:mm:ss (e.g. 1997-07-16T19:20:30) iii) Complete date plus hours, minutes and seconds with UTC designator: YYYY-MM-DDThh:mm:ssZ (e.g. 1997-07-16T19:20:30Z) Please be aware that if you don't provide the UTC designator (i.e., Z) the timestamp is generated using your local timezone. If only a date is specified, the time part used will equal to ``00:00:00``. ``path`` option sets the full path to the Swift object. Example: ``/v1/AUTH_account/c/o``. ``key`` option is the secret temporary URL key set on the Swift cluster. To set a key, run ``swift post -m "Temp-URL-Key: "``. To generate a prefix-based temporary URL use the ``--prefix-based`` option. This URL will contain the path to the prefix. Do not forget to append the desired objectname at the end of the path portion (and before the query portion) before sharing the URL. It is possible to use ISO 8601 UTC timestamps within the URL by using the ``--iso8601`` option. **Positional arguments:** ```` An HTTP method to allow for this temporary URL. Usually 'GET' or 'PUT'. ```` The amount of time in seconds the temporary URL will be valid for; or, if --absolute is passed, the Unix timestamp when the temporary URL will expire. ```` The full path to the Swift object. Example: /v1/AUTH_account/c/o or: http://saio:8080/v1/AUTH_account/c/o ```` The secret temporary URL key set on the Swift cluster. To set a key, run 'swift post -m "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"' **Optional arguments:** ``--absolute`` Interpret the positional argument as a Unix timestamp rather than a number of seconds in the future. ``--prefix-based`` If present, a prefix-based tempURL will be generated. Examples ~~~~~~~~ In this section we present some example usage of the ``swift`` CLI. To keep the examples as short as possible, these examples assume that the relevant authentication options have been set using environment variables. You can obtain the full list of commands and options available in the ``swift`` CLI by executing the following: .. code-block:: bash > swift --help > swift --help Simple examples --------------- List the existing swift containers: .. code-block:: bash > swift list container_1 Create a new container: .. code-block:: bash > swift post TestContainer Upload an object into a container: .. code-block:: bash > swift upload TestContainer testSwift.txt testSwift.txt List the contents of a container: .. code-block:: bash > swift list TestContainer testSwift.txt Copy an object to new destination: .. code-block:: bash > swift copy -d /DestContainer/testSwift.txt SourceContainer testSwift.txt SourceContainer/testSwift.txt copied to /DestContainer/testSwift.txt Delete an object from a container: .. code-block:: bash > swift delete TestContainer testSwift.txt testSwift.txt Delete a container: .. code-block:: bash > swift delete TestContainer TestContainer Display auth related authentication variables in shell friendly format: .. code-block:: bash > swift auth export OS_STORAGE_URL=http://127.0.0.1:8080/v1/AUTH_bf5e63572f7a420a83fcf0aa8c72c2c7 export OS_AUTH_TOKEN=c597015ae19943a18438b52ef3762e79 Download an object from a container: .. code-block:: bash > swift download TestContainer testSwift.txt testSwift.txt [auth 0.028s, headers 0.045s, total 0.045s, 0.002 MB/s] .. note:: To upload an object to a container, your current working directory must be where the file is located or you must provide the complete path to the file. In other words, the --object-name is an option that will upload file and name object to or upload directory and use as object prefix. In the case that you provide the complete path of the file, that complete path will be the name of the uploaded object. For example: .. code-block:: bash > swift upload TestContainer /home/swift/testSwift/testSwift.txt home/swift/testSwift/testSwift.txt > swift list TestContainer home/swift/testSwift/testSwift.txt More complex examples --------------------- Swift has a single object size limit of 5GiB. In order to upload files larger than this, we must create a large object that consists of smaller segments. The example below shows how to upload a large video file as a static large object in 1GiB segments: .. code-block:: bash > swift upload videos --use-slo --segment-size 1G myvideo.mp4 myvideo.mp4 segment 8 myvideo.mp4 segment 4 myvideo.mp4 segment 2 myvideo.mp4 segment 7 myvideo.mp4 segment 0 myvideo.mp4 segment 1 myvideo.mp4 segment 3 myvideo.mp4 segment 6 myvideo.mp4 segment 5 myvideo.mp4 This command will upload segments to a container named ``videos_segments``, and create a manifest file describing the entire object in the ``videos`` container. For more information on large objects, see the documentation `here `_. .. code-block:: bash > swift list videos myvideo.mp4 > swift list videos_segments myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000000 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000001 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000002 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000003 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000004 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000005 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000006 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000007 myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000008 Firstly, the key should be set, then generate a temporary URL for a Swift object: .. code-block:: bash > swift post -m "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4" > swift tempurl GET 6000 /v1/AUTH_bf5e63572f7a420a83fcf0aa8c72c2c7\ /firstcontainer/clean.sh b3968d0207b54ece87cccc06515a89d4 /v1/AUTH_/firstcontainer/clean.sh?temp_url_sig=\ 9218fc288cc09e5edd857b6a3d43cf2122b906dc&temp_url_expires=1472203614 ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/client-api.rst0000664000175000017500000001077400000000000022331 0ustar00zuulzuul00000000000000============================== The swiftclient.Connection API ============================== A low level API that provides methods for authentication and methods that correspond to the individual REST API calls described in the swift documentation. For usage details see the client docs: :mod:`swiftclient.client`. Authentication -------------- This section covers the various combinations of kwargs required when creating an instance of the ``Connection`` object for communicating with a swift object store. The combinations of options required for each authentication version are detailed below, but are just a subset of those that can be used to successfully authenticate. These are the most common and recommended combinations. Keystone Session ~~~~~~~~~~~~~~~~ .. code-block:: python from keystoneauth1 import session from keystoneauth1.identity import v3 # Create a password auth plugin auth = v3.Password(auth_url='http://127.0.0.1:5000/v3/', username='tester', password='testing', user_domain_name='Default', project_name='Default', project_domain_name='Default') # Create session keystone_session = session.Session(auth=auth) # Create swiftclient Connection swift_conn = Connection(session=keystone_session) Keystone v3 ~~~~~~~~~~~ .. code-block:: python _authurl = 'http://127.0.0.1:5000/v3/' _auth_version = '3' _user = 'tester' _key = 'testing' _os_options = { 'user_domain_name': 'Default', 'project_domain_name': 'Default', 'project_name': 'Default' } conn = Connection( authurl=_authurl, user=_user, key=_key, os_options=_os_options, auth_version=_auth_version ) Keystone v2 ~~~~~~~~~~~ .. code-block:: python _authurl = 'http://127.0.0.1:5000/v2.0/' _auth_version = '2' _user = 'tester' _key = 'testing' _tenant_name = 'test' conn = Connection( authurl=_authurl, user=_user, key=_key, tenant_name=_tenant_name, auth_version=_auth_version ) Legacy Auth ~~~~~~~~~~~ .. code-block:: python _authurl = 'http://127.0.0.1:8080/' _auth_version = '1' _user = 'tester' _key = 'testing' _tenant_name = 'test' conn = Connection( authurl=_authurl, user=_user, key=_key, tenant_name=_tenant_name, auth_version=_auth_version ) Examples -------- In this section we present some simple code examples that demonstrate the usage of the ``Connection`` API. You can find full details of the options and methods available to the ``Connection`` API in the docstring generated documentation: :mod:`swiftclient.client`. List the available containers: .. code-block:: python resp_headers, containers = conn.get_account() print("Response headers: %s" % resp_headers) for container in containers: print(container) Create a new container: .. code-block:: python container = 'new-container' conn.put_container(container) resp_headers, containers = conn.get_account() if container in containers: print("The container was created") Create a new object with the contents of a local text file: .. code-block:: python container = 'new-container' with open('local.txt', 'r') as local: conn.put_object( container, 'local_object.txt', contents=local, content_type='text/plain' ) Confirm presence of the object: .. code-block:: python obj = 'local_object.txt' container = 'new-container' try: resp_headers = conn.head_object(container, obj) print('The object was successfully created') except ClientException as e: if e.http_status = '404': print('The object was not found') else: print('An error occurred checking for the existence of the object') Download the created object: .. code-block:: python obj = 'local_object.txt' container = 'new-container' resp_headers, obj_contents = conn.get_object(container, obj) with open('local_copy.txt', 'w') as local: local.write(obj_contents) Delete the created object: .. code-block:: python obj = 'local_object.txt' container = 'new-container' try: conn.delete_object(container, obj) print("Successfully deleted the object") except ClientException as e: print("Failed to delete the object with error: %s" % e) ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/conf.py0000664000175000017500000001475700000000000021056 0ustar00zuulzuul00000000000000# -*- coding: utf-8 -*- # # Swiftclient documentation build configuration file, created by # sphinx-quickstart on Tue Apr 17 02:17:37 2012. # # This file is execfile()d with the current directory set to its containing # dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import sys import os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # sys.path.append(os.path.abspath('.')) BASE_DIR = os.path.dirname(os.path.abspath(__file__)) ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) sys.path.insert(0, ROOT) # -- General configuration ---------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'openstackdocstheme'] autoclass_content = 'both' autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. # source_encoding = 'utf-8' # The master toctree document. master_doc = 'index' # General information about the project. copyright = '2013-2016 OpenStack, LLC.' # -- Options for openstackdocstheme ------------------------------------------- openstackdocs_repo_name = 'openstack/python-swiftclient' openstackdocs_bug_project = 'python-swiftclient' openstackdocs_bug_tag = '' openstackdocs_pdf_link = True # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: # today = '' # Else, today_fmt is used as the format for a strftime call. # today_fmt = '%B %d, %Y' # List of documents that shouldn't be included in the build. # unused_docs = [] # List of directories, relative to source directory, that shouldn't be searched # for source files. exclude_trees = [] # The reST default role (used for this markup: `text`) to use for all # documents. # default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. # add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). # add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. # show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'native' # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. html_theme = 'openstackdocs' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # html_theme_options = {} html_theme_options = {'show_other_versions': True} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". # html_title = None # A shorter title for the navigation bar. Default is the same as html_title. # html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. # html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. # html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. # html_use_smartypants = True # Custom sidebar templates, maps document names to template names. # html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. # html_additional_pages = {} # If false, no module index is generated. # html_use_modindex = True # If false, no index is generated. # html_use_index = True # If true, the index is split into individual pages for each letter. # html_split_index = False # If true, links to the reST sources are added to the pages. # html_show_sourcelink = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. # html_use_opensearch = '' # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). # html_file_suffix = '' # Output file base name for HTML help builder. htmlhelp_basename = 'SwiftClientwebdoc' # -- Options for LaTeX output ------------------------------------------------- # The paper size ('letter' or 'a4'). # latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). # latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]) latex_documents = [ ('index', 'doc-python-swiftclient.tex', 'SwiftClient Documentation', 'OpenStack, LLC.', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. # latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. # latex_use_parts = False # Additional stuff for the LaTeX preamble. # latex_preamble = '' # Documents to append as an appendix to all manuals. # latex_appendices = [] # If false, no module index is generated. # latex_use_modindex = True latex_use_xindy = False ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1645609542.0976722 python-swiftclient-3.13.1/doc/source/contributor/0000775000175000017500000000000000000000000022113 5ustar00zuulzuul00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/contributor/contributing.rst0000664000175000017500000000130000000000000025346 0ustar00zuulzuul00000000000000============================ So You Want to Contribute... ============================ For general information on contributing to OpenStack, please check out the `contributor guide `_ to get started. It covers all the basics that are common to all OpenStack projects: the accounts you need, the basics of interacting with our Gerrit review system, how we communicate as a community, etc. The python-swiftclient is maintained by the OpenStack Swift project. To understand our development process and how you can contribute to it, please look at the Swift project's general contributor's page: http://docs.openstack.org/swift/latest/contributor/contributing.html././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/index.rst0000664000175000017500000000214100000000000021400 0ustar00zuulzuul00000000000000====================================== Welcome to the python-swiftclient Docs ====================================== Introduction ~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 introduction Developer Documentation ~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 contributor/contributing cli/index service-api client-api Code-Generated Documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 swiftclient Indices and tables ~~~~~~~~~~~~~~~~~~ * :ref:`genindex` * :ref:`modindex` * :ref:`search` License ~~~~~~~ Copyright 2013 OpenStack, LLC. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at * http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/introduction.rst0000664000175000017500000001022700000000000023016 0ustar00zuulzuul00000000000000============ Introduction ============ Where to Start? ~~~~~~~~~~~~~~~ The ``python-swiftclient`` project comprises a command line tool and two separate APIs for accessing swift programmatically. Choosing the most appropriate method for a given use case is the first problem a user needs to solve. Use Cases --------- Alongside the command line tool, the ``python-swiftclient`` includes two levels of API: * A low level client API that provides simple Python wrappers around the various authentication mechanisms and the individual HTTP requests. * A high level service API that provides methods for performing common operations in parallel on a thread pool. Example use cases: * Uploading and retrieving data Use the command line tool if you are simply uploading and downloading files and directories to and from your filesystem. The command line tool can be integrated into a shell script to automate tasks. * Integrating into an automated Python workflow Use the ``SwiftService`` API to perform operations offered by the CLI if your use case requires integration with a Python-based workflow. This method offers greater control and flexibility over individual object operations, such as the metadata set on each object. The ``SwiftService`` class provides methods to perform multiple sets of operations against a swift object store using a configurable shared thread pool. A single instance of the ``SwiftService`` class can be shared between multiple threads in your own code. * Developing an application in Python to access a swift object store Use the ``SwiftService`` API to develop Python applications that use swift to store and retrieve objects. A ``SwiftService`` instance provides a configurable thread pool for performing all operations supported by the CLI. * Fine-grained control over threading or the requests being performed Use the ``Connection`` API if your use case requires fine grained control over advanced features or you wish to use your own existing threading model. Examples of advanced features requiring the use of the ``Connection`` API include creating an SLO manifest that references already existing objects, or fine grained control over the query strings supplied with each HTTP request. Important considerations ~~~~~~~~~~~~~~~~~~~~~~~~ This section covers some important considerations, helpful hints, and things to avoid when integrating an object store into your workflow. An object store is not a filesystem ----------------------------------- It cannot be stressed enough that your usage of the object store should reflect the proper use case, and not treat the storage like a traditional filesystem. There are two main restrictions to bear in mind when designing an application that uses an object store: * You cannot rename objects. Due to fact that the name of an object is one of the factors that determines where the object and its replicas are stored, renaming would require multiple copies of the data to be moved between physical storage devices. If you want to rename an object you must upload to the new location, or make a server side copy request to the new location, and then delete the original. * You cannot modify objects. Objects are stored in multiple locations and are checked for integrity based on the MD5 sum calculated during upload. In order to modify the contents of an object, the entire desired contents must be re-uploaded. In certain special cases it is possible to work around this restriction using large objects, but no general file-like access is available to modify a stored object. Objects cannot be locked ------------------------ There is no mechanism to perform a combination of reading the data/metadata from an object and writing an update to that data/metadata in an atomic way. Any user with access to a container could update the contents or metadata associated with an object at any time. Workflows that assume that no updates have been made since the last read of an object should be discouraged. Enabling a workflow of this type requires an external object locking mechanism and/or cooperation between all clients accessing the data. ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1645609512.0 python-swiftclient-3.13.1/doc/source/service-api.rst0000664000175000017500000007561200000000000022515 0ustar00zuulzuul00000000000000================================ The swiftclient.SwiftService API ================================ A higher-level API aimed at allowing developers an easy way to perform multiple operations asynchronously using a configurable thread pool. Documentation for each service method call can be found here: :mod:`swiftclient.service`. Authentication -------------- This section covers the various options for authenticating with a swift object store. The combinations of options required for each authentication version are detailed below. Once again, these are just a subset of those that can be used to successfully authenticate, but they are the most common and recommended. The relevant authentication options are presented as python dictionaries that should be added to any other options you are supplying to your ``SwiftService`` instance. As indicated in the python code, you can also set these options as environment variables that will be loaded automatically if the relevant option is not specified. The ``SwiftService`` authentication attempts to automatically select the auth version based on the combination of options specified, but supplying options from multiple different auth versions can cause unexpected behaviour. .. note:: Leftover environment variables are a common source of confusion when authorization fails. Keystone V3 ~~~~~~~~~~~ .. code-block:: python { ... "auth_version": environ.get('ST_AUTH_VERSION'), # Should be '3' "os_username": environ.get('OS_USERNAME'), "os_password": environ.get('OS_PASSWORD'), "os_project_name": environ.get('OS_PROJECT_NAME'), "os_project_domain_name": environ.get('OS_PROJECT_DOMAIN_NAME'), "os_auth_url": environ.get('OS_AUTH_URL'), ... } .. code-block:: python { ... "auth_version": environ.get('ST_AUTH_VERSION'), # Should be '3' "os_username": environ.get('OS_USERNAME'), "os_password": environ.get('OS_PASSWORD'), "os_project_id": environ.get('OS_PROJECT_ID'), "os_project_domain_id": environ.get('OS_PROJECT_DOMAIN_ID'), "os_auth_url": environ.get('OS_AUTH_URL'), ... } Keystone V2 ~~~~~~~~~~~ .. code-block:: python { ... "auth_version": environ.get('ST_AUTH_VERSION'), # Should be '2.0' "os_username": environ.get('OS_USERNAME'), "os_password": environ.get('OS_PASSWORD'), "os_tenant_name": environ.get('OS_TENANT_NAME'), "os_auth_url": environ.get('OS_AUTH_URL'), ... } Legacy Auth ~~~~~~~~~~~ .. code-block:: python { ... "auth_version": environ.get('ST_AUTH_VERSION'), # Should be '1.0' "auth": environ.get('ST_AUTH'), "user": environ.get('ST_USER'), "key": environ.get('ST_KEY'), ... } Configuration ------------- When you create an instance of a ``SwiftService``, you can override a collection of default options to suit your use case. Typically, the defaults are sensible to get us started, but depending on your needs you might want to tweak them to improve performance (options affecting large objects and thread counts can significantly alter performance in the right situation). Service level defaults and some extra options can also be overridden on a per-operation (or even in some cases per-object) basis, and you will call out which options affect which operations later in the document. The configuration of the service API is performed using an options dictionary passed to the ``SwiftService`` during initialisation. The options available in this dictionary are described below, along with their defaults: Options ~~~~~~~ ``retries``: ``5`` The number of times that the library should attempt to retry HTTP actions before giving up and reporting a failure. ``container_threads``: ``10`` ``object_dd_threads``: ``10`` ``object_uu_threads``: ``10`` ``segment_threads``: ``10`` The above options determine the size of the available thread pools for performing swift operations. Container operations (such as listing a container) operate in the container threads, and a similar pattern applies to object and segment threads. .. note:: Object threads are separated into two separate thread pools: ``uu`` and ``dd``. This stands for "upload/update" and "download/delete", and the corresponding actions will be run on separate threads pools. ``segment_size``: ``None`` If specified, this option enables uploading of large objects. Should the object being uploaded be larger than 5G in size, this option is mandatory otherwise the upload will fail. This option should be specified as a size in bytes. ``use_slo``: ``False`` Used in combination with the above option, ``use_slo`` will upload large objects as static rather than dynamic. Only static large objects provide error checking for the downloaded object, so we recommend this option. ``segment_container``: ``None`` Allows the user to select the container into which large object segments will be uploaded. We do not recommend changing this value as it could make locating orphaned segments more difficult in the case of errors. ``leave_segments``: ``False`` Setting this option to true means that when deleting or overwriting a large object, its segments will be left in the object store and must be cleaned up manually. This option can be useful when sharing large object segments between multiple objects in more advanced scenarios, but must be treated with care, as it could lead to ever increasing storage usage. ``changed``: ``None`` This option affects uploads and simply means that those objects which already exist in the object store will not be overwritten if the ``mtime`` and size of the source is the same as the existing object. ``skip_identical``: ``False`` A slightly more thorough case of the above, but rather than ``mtime`` and size uses an object's ``MD5 sum``. ``yes_all``: ``False`` This options affects only download and delete, and in each case must be specified in order to download/delete the entire contents of an account. This option has no effect on any other calls. ``no_download``: ``False`` This option only affects download and means that all operations proceed as normal with the exception that no data is written to disk. ``header``: ``[]`` Used with upload and post operations to set headers on objects. Headers are specified as colon separated strings, e.g. "content-type:text/plain". ``meta``: ``[]`` Used to set metadata on an object similarly to headers. .. note:: Setting metadata is a destructive operation, so when updating one of many metadata values all desired metadata for an object must be re-applied. ``long``: ``False`` Affects only list operations, and results in more metrics being made available in the results at the expense of lower performance. ``fail_fast``: ``False`` Applies to delete and upload operations, and attempts to abort queued tasks in the event of errors. ``prefix``: ``None`` Affects list operations; only objects with the given prefix will be returned/affected. It is not advisable to set at the service level, as those operations that call list to discover objects on which they should operate will also be affected. ``delimiter``: ``None`` Affects list operations, and means that listings only contain results up to the first instance of the delimiter in the object name. This is useful for working with objects containing '/' in their names to simulate folder structures. ``dir_marker``: ``False`` Affects uploads, and allows empty 'pseudofolder' objects to be created when the source of an upload is ``None``. ``checksum``: ``True`` Affects uploads and downloads. If set check md5 sum for the transfer. ``shuffle``: ``False`` When downloading objects, the default behaviour of the CLI is to shuffle lists of objects in order to spread the load on storage drives when multiple clients are downloading the same files to multiple locations (e.g. in the event of distributing an update). When using the ``SwiftService`` directly, object downloads are scheduled in the same order as they appear in the container listing. When combined with a single download thread this means that objects are downloaded in lexically-sorted order. Setting this option to ``True`` gives the same shuffling behaviour as the CLI. ``destination``: ``None`` When copying objects, this specifies the destination where the object will be copied to. The default of None means copy will be the same as source. ``fresh_metadata``: ``None`` When copying objects, this specifies that the object metadata on the source will *not* be applied to the destination object - the destination object will have a new fresh set of metadata that includes *only* the metadata specified in the meta option if any at all. Other available options can be found in ``swiftclient/service.py`` in the source code for ``python-swiftclient``. Each ``SwiftService`` method also allows for an optional dictionary to override those specified at init time, and the appropriate docstrings show which options modify each method's behaviour. Available Operations -------------------- Each operation provided by the service API may raise a ``SwiftError`` or ``ClientException`` for any call that fails completely (or a call which performs only one operation at an account or container level). In the case of a successful call an operation returns one of the following: * A dictionary detailing the results of a single operation. * An iterator that produces result dictionaries (for calls that perform multiple sub-operations). A result dictionary can indicate either the success or failure of an individual operation (detailed in the ``success`` key), and will either contain the successful result, or an ``error`` key detailing the error encountered (usually an instance of Exception). An example result dictionary is given below: .. code-block:: python result = { 'action': 'download_object', 'success': True, 'container': container, 'object': obj, 'path': path, 'start_time': start_time, 'finish_time': finish_time, 'headers_receipt': headers_receipt, 'auth_end_time': conn.auth_end_time, 'read_length': bytes_read, 'attempts': conn.attempts } All the possible ``action`` values are detailed below: .. code-block:: python [ 'stat_account', 'stat_container', 'stat_object', 'post_account', 'post_container', 'post_object', 'list_part', # list yields zero or more 'list_part' results 'download_object', 'create_container', # from upload 'create_dir_marker', # from upload 'upload_object', 'upload_segment', 'delete_container', 'delete_object', 'delete_segment', # from delete_object operations 'capabilities', ] Stat ~~~~ Stat can be called against an account, a container, or a list of objects to get account stats, container stats or information about the given objects. In the first two cases a dictionary is returned containing the results of the operation, and in the case of a list of object names being supplied, an iterator over the results generated for each object is returned. Information returned includes the amount of data used by the given object/container/account and any headers or metadata set (this includes user set data as well as content-type and modification times). See :mod:`swiftclient.service.SwiftService.stat` for docs generated from the method docstring. Valid calls for this method are as follows: * ``stat([options])``: Returns stats for the configured account. * ``stat(, [options])``: Returns stats for the given container. * ``stat(, , [options])``: Returns stats for each of the given objects in the given container (through the returned iterator). Results from stat are dictionaries indicating the success or failure of each operation. In the case of a successful stat against an account or container, the method returns immediately with one of the following results: .. code-block:: python { 'action': 'stat_account', 'success': True, 'items': items, 'headers': headers } .. code-block:: python { 'action': 'stat_container', 'container': , 'success': True, 'items': items, 'headers': headers } In the case of stat called against a list of objects, the method returns a generator that returns the results of individual object stat operations as they are performed on the thread pool: .. code-block:: python { 'action': 'stat_object', 'object': , 'container': , 'success': True, 'items': items, 'headers': headers } In the case of a failure the dictionary returned will indicate that the operation was not successful, and will include the keys below: .. code-block:: python { 'action': <'stat_object'|'stat_container'|'stat_account'>, 'object': <'object_name'>, # Only for stat with objects list 'container': , # Only for stat with objects list or container 'success': False, 'error': , 'traceback': , 'error_timestamp': } .. topic:: Example The code below demonstrates the use of ``stat`` to retrieve the headers for a given list of objects in a container using 20 threads. The code creates a mapping from object name to headers which is then pretty printed to the log. .. literalinclude:: ../../examples/stat.py :language: python List ~~~~ List can be called against an account or a container to retrieve the containers or objects contained within them. Each call returns an iterator that returns pages of results (by default, up to 10000 results in each page). See :mod:`swiftclient.service.SwiftService.list` for docs generated from the method docstring. If the given container or account does not exist, the list method will raise a ``SwiftError``, but for all other success/failures a dictionary is returned. Each successfully listed page returns a dictionary as described below: .. code-block:: python { 'action': <'list_account_part'|'list_container_part'>, 'container': , # Only for listing a container 'prefix': , # The prefix of returned objects/containers 'success': True, 'listing': [Item], # A list of results # (only in the event of success) 'marker': # The last item name in the list # (only in the event of success) } Where an item contains the following keys: .. code-block:: python { 'name': , 'bytes': 10485760, 'last_modified': '2014-12-11T12:02:38.774540', 'hash': 'fb938269cbeabe4c234e1127bbd3b74a', 'content_type': 'application/octet-stream', 'meta': # Full metadata listing from stat'ing each object # this key only exists if 'long' is specified in options } Any failure listing an account or container that exists will return a failure dictionary as described below: .. code-block:: python { 'action': <'list_account_part'|'list_container_part'>,, 'container': container, # Only for listing a container 'prefix': options['prefix'], 'success': success, 'marker': marker, 'error': error, 'traceback': , 'error_timestamp': } .. topic:: Example The code below demonstrates the use of ``list`` to list all items in a container that are over 10MiB in size: .. literalinclude:: ../../examples/list.py :language: python Post ~~~~ Post can be called against an account, container or list of objects in order to update the metadata attached to the given items. In the first two cases a single dictionary is returned containing the results of the operation, and in the case of a list of objects being supplied, an iterator over the results generated for each object post is returned. Each element of the object list may be a plain string of the object name, or a ``SwiftPostObject`` that allows finer control over the options and metadata applied to each of the individual post operations. When a string is given for the object name, the options and metadata applied are a combination of those supplied to the call to ``post()`` and the defaults of the ``SwiftService`` object. If the given container or account does not exist, the ``post`` method will raise a ``SwiftError``. Successful metadata update results are dictionaries as described below: .. code-block:: python { 'action': <'post_account'|'post_container'|'post_object'>, 'success': True, 'container': , 'object': , 'headers': {}, 'response_dict': } .. note:: Updating user metadata keys will not only add any specified keys, but will also remove user metadata that has previously been set. This means that each time user metadata is updated, the complete set of desired key-value pairs must be specified. .. topic:: Example The code below demonstrates the use of ``post`` to set an archive folder in a given container to expire after a 24 hour delay: .. literalinclude:: ../../examples/post.py :language: python Download ~~~~~~~~ Download can be called against an entire account, a single container, or a list of objects in a given container. Each element of the object list is a string detailing the full name of an object to download. In order to download the full contents of an entire account, you must set the value of ``yes_all`` to ``True`` in the ``options`` dictionary supplied to either the ``SwiftService`` instance or the call to ``download``. If the given container or account does not exist, the ``download`` method will raise a ``SwiftError``, otherwise an iterator over the results generated for each object download is returned. See :mod:`swiftclient.service.SwiftService.download` for docs generated from the method docstring. For each successfully downloaded object, the results returned by the iterator will be a dictionary as described below (results are not returned for completed container or object segment downloads): .. code-block:: python { 'action': 'download_object', 'container': , 'object': , 'success': True, 'path': , 'pseudodir': , 'start_time':