Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
76 commits
Select commit Hold shift + click to select a range
14489b8
rst files renamed according to package name
dparamonov-reef Feb 28, 2019
663760f
Added docs for b2sdk.transferer
dparamonov-reef Feb 28, 2019
2e370ea
Unneeded file removed
dparamonov-reef Feb 28, 2019
d76520b
Table of contents updated
dparamonov-reef Feb 28, 2019
26ecabb
Docstrings fixed in order to eliminate warnings during docs build
dparamonov-reef Feb 28, 2019
bffcad1
Docstrings for b2sdk.api module updated
dparamonov-reef Mar 1, 2019
89167bb
Correctly set types in docstrings
dparamonov-reef Mar 1, 2019
aa1d920
Docstrings for b2sdk.b2hhtp module updated
dparamonov-reef Mar 1, 2019
8ac16fd
Docstrings for b2sdk.bounded_queue_executor were updated
dparamonov-reef Mar 1, 2019
ae455c5
Docstrings for objects in b2sdk.bucket module added
dparamonov-reef Mar 2, 2019
65bd9c8
Formatting fixed
dparamonov-reef Mar 2, 2019
31d67aa
Docstrings added for objects from b2sdk.progress module
dparamonov-reef Mar 2, 2019
55d5d90
Docstrings added for objects in b2sdk.sync.action module
dparamonov-reef Mar 2, 2019
c8d3a8b
Docstrings added for objects in b2sdk.sync.exception module
dparamonov-reef Mar 2, 2019
f60c82a
Docstrings added for objects in b2sdk.sync.file module
dparamonov-reef Mar 2, 2019
6f03ac1
Docstrings added for objects in b2sdk.sync.folder_parser module
dparamonov-reef Mar 2, 2019
be569e9
Typos fixed
dparamonov-reef Mar 2, 2019
9c42cb1
Docstrings for reporter objects updated
dparamonov-reef Mar 2, 2019
a493949
Docstrings added for objects in module b2sdk.sync.folder
dparamonov-reef Mar 2, 2019
7f2db66
Docstrings added for objects in policy_manager module
dparamonov-reef Mar 4, 2019
32cd955
Docstrings adde for objects in b2sdk.sync.policy module
dparamonov-reef Mar 4, 2019
fca7a66
Docstrings added for objects in b2sdk.sync.report module
dparamonov-reef Mar 4, 2019
c79216e
Docstrings added for objects in b2sdk.sync.scan_policies module
dparamonov-reef Mar 4, 2019
f35009e
Docstrings updated, strings -> objects
dparamonov-reef Mar 4, 2019
ed6ccc7
flie and folder objects' types updated in docstrings
dparamonov-reef Mar 4, 2019
aabd754
Docstrings added for objects in b2sdk.sync.sync module
dparamonov-reef Mar 4, 2019
ad765ce
Module content entries removed from ToC as uneeded
dparamonov-reef Mar 4, 2019
e965775
Rename B2_Command_Line_Tool to B2 Python SDK
dparamonov-reef Mar 4, 2019
b82ff7e
Sphinx theme changed to sphinx_rtd_theme
dparamonov-reef Mar 5, 2019
d2e7a6e
Docstrings added for objects in module b2sdk.account_info.abstract
dparamonov-reef Mar 5, 2019
b434ce4
Docstrings added for objects in b2sdk.account_info.exception module
dparamonov-reef Mar 5, 2019
dd1e124
Docstrings added for objects in b2sdk.account_info.sqlite_account_info
dparamonov-reef Mar 5, 2019
2d58439
Docstrings added for objects in b2sdk.account_info.upload_url_pool
dparamonov-reef Mar 5, 2019
a175b77
docstring fixed
dparamonov-reef Mar 5, 2019
4b9d2a1
Docstrings added for objects in b2sdk.account_info.in_memory
dparamonov-reef Mar 5, 2019
41e5a0f
indentation fixed in docstrings
dparamonov-reef Mar 5, 2019
628464d
Docs structure updated
dparamonov-reef Mar 5, 2019
cbddaae
Docstrings added for objects in b2sdk.utils module
dparamonov-reef Mar 5, 2019
ad7664c
Fixed quoting in docstring
dparamonov-reef Mar 5, 2019
8104a77
docstring added to url_for_api function
dparamonov-reef Mar 5, 2019
91958f9
Exclude set_auth_data_with_schema_0_for_test from a set of documented…
dparamonov-reef Mar 9, 2019
3d9ed39
Merge branch 'keyboard-interrupt' into sphinx-docs
dparamonov-reef Mar 9, 2019
d787c89
Fix formatting issues
dparamonov-reef Mar 9, 2019
09d37aa
Delete parse_args module and related unit tests
dparamonov-reef Mar 9, 2019
66f2a4a
Remove repr_dict_deterministically function
dparamonov-reef Mar 9, 2019
d7f9ed7
Remove trailing whitespaces from docstrings
dparamonov-reef Mar 10, 2019
5fe94b6
Remove extra spaces in docstrings
dparamonov-reef Mar 11, 2019
db77fd8
Add installation guide docs template
dparamonov-reef Mar 13, 2019
81dedf5
Add tutorial docs template
dparamonov-reef Mar 13, 2019
70ee755
Update table of contents
dparamonov-reef Mar 13, 2019
83d8b15
Add overview section to the docs
dparamonov-reef Mar 13, 2019
188e1c5
Add installation instructions
dparamonov-reef Mar 13, 2019
0b30b6b
Remove extra spaces in docstrings
dparamonov-reef Mar 16, 2019
ad68ea0
Add building docs to CI
ppolewicz Mar 27, 2019
70af4c4
Add docs coverage checker to CI
ppolewicz Mar 28, 2019
5aa6a1c
Fail on syntax issues in docs
ppolewicz Mar 28, 2019
26b5bc8
Add documentation rebuilding helper script
ppolewicz Mar 29, 2019
157c3b9
Add requirements-doc.txt installation to release instructions
ppolewicz Mar 29, 2019
9307db4
Change "View source" button to "Edit on GitHub"
ppolewicz Mar 29, 2019
6705a34
Change version to 0.1.0 to indicate that the API will change soon
ppolewicz Mar 29, 2019
5a2bbc0
Re-enable incremental documentation building
ppolewicz Mar 29, 2019
b10edb5
Fix spacing in config (thanks yapf!)
ppolewicz Mar 29, 2019
cf7b378
Add requirements-doc.txt
ppolewicz Mar 29, 2019
5e2f142
SqliteAccountInfo database schema in documentation
mzukowski-reef Mar 29, 2019
2fe18ab
Version in setup.py from b2sdk.version
mzukowski-reef Mar 29, 2019
a883050
Sort out sqlite_account_info_schema.py
ppolewicz Mar 29, 2019
42845f8
Add plantuml to documentation generator, make docs in CI
ppolewicz Mar 29, 2019
8f7acce
Try to generate documentation in pre-commit
ppolewicz Mar 29, 2019
a3aeb89
Fix travis doc build
ppolewicz Mar 29, 2019
5324e48
Try to make doc builder work
ppolewicz Mar 29, 2019
b1d229f
Improve sqlite_account_info docs
ppolewicz Mar 31, 2019
5687bd0
Add .readthedocs.yml
ppolewicz Mar 31, 2019
61efe95
Fix python nightly builds in Travis
ppolewicz Mar 31, 2019
f02a824
Fix building docs at readthedocs
ppolewicz Mar 31, 2019
ca6e353
Improve documentation
ppolewicz Apr 1, 2019
4f1f9fb
Remove CLI things
ppolewicz Apr 2, 2019
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: doc/source/conf.py

# Optionally build your docs in additional formats such as PDF and ePub
formats: all

# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: requirements.txt
- method: pip
path: .
extra_requirements:
- doc
system_packages: false
45 changes: 43 additions & 2 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ python:
- 3.4
- 3.5
- 3.6
- nightly
# stock versions of pypy provided by Travis CI don't work with cryptography 1.0
#- pypy
#- pypy3
Expand All @@ -28,7 +27,6 @@ branches:
matrix:
allow_failures:
- python: pypy3 # https://github.com/pyca/cryptography/issues/2880
- python: nightly # on 2018-02-14 it was found failing installation with ValueError: bad marshal data (unknown type code)
include:
# Source Code Analysis is slow, so we run it just once on Python 2 and once on Python 3
- python: 2.7
Expand All @@ -41,6 +39,11 @@ matrix:
dist: xenial
sudo: true

# Enable nightly without globally enabling sudo and xenial for other build jobs
- python: nightly
dist: xenial
sudo: true

# Travis CI doesn't support OSX python builds officially,
# but that won't stop us...
# ... or maybe it will. It's now getting this error:
Expand Down Expand Up @@ -82,6 +85,11 @@ matrix:
- python: 3.5
env: MODE=coverage

# doc
- python: 3.6
env: MODE=doc
sudo: true

cache:
- pip
- directories:
Expand All @@ -97,6 +105,7 @@ cache:
- $HOME/.virtualenvs/osx-python3
#- /usr/local/Cellar/python # see comment in the install script
#- /usr/local/Cellar/python3
- $HOME/plantuml.jar
before_install:
- uname -a
- if [[ "$TRAVIS_OS_NAME" != "osx" ]]; then lsb_release -a; fi
Expand Down Expand Up @@ -222,6 +231,15 @@ install:
- pip install -r requirements.txt
- pip install -r requirements-setup.txt
- pip install -r requirements-test.txt
- |
if [ "$MODE" == 'doc' ]; then
sudo apt-get install graphviz
pip install -r requirements-doc.txt

# install plantuml without sudo
travis_retry wget http://sourceforge.net/projects/plantuml/files/plantuml.1.2019.3.jar/downloadA -O ~/plantuml.jar
alias plantuml="java -jar ~/plantuml.jar"
fi

- |
# coverage has additional requirements
Expand Down Expand Up @@ -299,6 +317,29 @@ script:
python setup.py install
fi
fi

# build docs
- |
# needs package to be installed already
if [ "$MODE" == 'doc' ]; then
cd doc
make html
cd ..
fi

# check docs coverage
- |
# needs package to be installed already
if [ "$MODE" == 'doc' ]; then
cd doc
make coverage
cd ..
if [ "$(wc -l < doc/build/coverage/python.txt)" != '2' ]; then
cat doc/build/coverage/python.txt >&2
return 1
fi
fi

# custom things specific to b2 SDK
- if [ -n "$TEST_ACCOUNT_ID" -a "$MODE" == "TEST_RAW_API" ]; then python -m b2sdk.__main__ test_raw_api; else echo skip; fi

Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This repository contains a client library and a few handy utilities for easy access to all of the capabilities of B2 Cloud Storage.

[B2 command-line tool](https://github.com/Backblaze/B2_Command_Line_Tool) is an exampl of how it can be used to provide command-line access to the B2 service, but there are many possible applications (including FUSE filesystems, storage backend drivers for backup applications etc).
[B2 command-line tool](https://github.com/Backblaze/B2_Command_Line_Tool) is an example of how it can be used to provide command-line access to the B2 service, but there are many possible applications (including FUSE filesystems, storage backend drivers for backup applications etc).

# Installation

Expand All @@ -26,13 +26,13 @@ b2sdk follows [Semantic Versioning](https://semver.org/) policy, so in essence t
Therefore when setting up b2sdk as a dependency, please make sure to match the version appropriately, for example you could put this in your `requirements.txt` to make sure your code is compatible with the `b2sdk` version your user will get from pypi:

```
b2sdk>=1.0.0,<2.0.0
b2sdk>=0.0.0,<1.0.0
```


# Release History

## 1.0.0 (February ????, 2019)
## 0.1.0 (2019-04-??)

Initial official release of SDK as a separate package (until now it was a part of B2 CLI)

Expand Down
2 changes: 1 addition & 1 deletion README.release.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Release Process

- Get the latest versions of dependencies
- `pip install --upgrade --upgrade-strategy eager -r requirements.txt -r requirements-test.txt -r requirements-setup.txt`
- `pip install --upgrade --upgrade-strategy eager -r requirements.txt -r requirements-test.txt -r requirements-setup.txt -r requirements-doc.txt`
- Bump the version number to an even number.
- version number is in: `b2/version.py`, `README.md`, and `setup.py`.
- Update the release history in README.md.
Expand Down
128 changes: 120 additions & 8 deletions b2sdk/account_info/abstract.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ class AbstractAccountInfo(object):

@classmethod
def all_capabilities(cls):
"""
Return a list of all possible capabilities

:rtype: list
"""
return cls.ALL_CAPABILITIES

@abstractmethod
Expand All @@ -58,64 +63,112 @@ def clear(self):
def refresh_entire_bucket_name_cache(self, name_id_iterable):
"""
Removes all previous name-to-id mappings and stores new ones.

:param name_id_iterable: a list of tuples of the form (name, id)
:type name_id_iterable: list
"""

@abstractmethod
def remove_bucket_name(self, bucket_name):
"""
Removes one entry from the bucket name cache.

:param bucket_name: a bucket name
:type bucket_name: str
"""

@abstractmethod
def save_bucket(self, bucket):
"""
Remembers the ID for a bucket name.

:param bucket: a Bucket object
:type bucket: b2sdk.bucket.Bucket
"""

@abstractmethod
def get_bucket_id_or_none_from_bucket_name(self, bucket_name):
"""
Looks up the bucket ID for a given bucket name.

:param bucket_name: a bucket name
:type bucket_name: str
:return bucket ID or None:
:rtype: str, None
"""

@abstractmethod
def clear_bucket_upload_data(self, bucket_id):
"""
Removes all upload URLs for the given bucket.

:param bucket_id: a bucket ID
:type bucket_id: str
"""

@abstractmethod
def get_account_id(self):
""" returns account_id or raises MissingAccountData exception """
"""
Returns account_id or raises MissingAccountData exception

:rtype: str
"""

@abstractmethod
def get_account_id_or_app_key_id(self):
""" returns the account id or key id used to authenticate """
"""
Returns the account id or key id used to authenticate

:rtype: str
"""

@abstractmethod
def get_account_auth_token(self):
""" returns account_auth_token or raises MissingAccountData exception """
"""
Returns account_auth_token or raises MissingAccountData exception

:rtype: str
"""

@abstractmethod
def get_api_url(self):
""" returns api_url or raises MissingAccountData exception """
"""
Returns api_url or raises MissingAccountData exception

:rtype: str
"""

@abstractmethod
def get_application_key(self):
""" returns application_key or raises MissingAccountData exception """
"""
Returns application_key or raises MissingAccountData exception

:rtype: str
"""

@abstractmethod
def get_download_url(self):
""" returns download_url or raises MissingAccountData exception """
"""
Returns download_url or raises MissingAccountData exception

:rtype: str
"""

@abstractmethod
def get_realm(self):
""" returns realm or raises MissingAccountData exception """
"""
Returns realm or raises MissingAccountData exception

:rtype: str
"""

@abstractmethod
def get_minimum_part_size(self):
"""
:return: returns the minimum number of bytes in a part of a large file
Return the minimum number of bytes in a part of a large file

:return: number of bytes
:rtype: int
"""

@abstractmethod
Expand All @@ -124,6 +177,8 @@ def get_allowed(self):
An 'allowed' dict, as returned by b2_authorize_account.
Never None; for account info that was saved before 'allowed' existed,
returns DEFAULT_ALLOWED.

:rtype: dict
"""

@limit_trace_arguments(only=['self', 'api_url', 'download_url', 'minimum_part_size', 'realm'])
Expand All @@ -149,6 +204,25 @@ def set_auth_data(
a bucketName field. For keys with bucket restrictions, the name of the bucket is looked
up and stored, too. The console_tool does everything by bucket name, so it's convenient
to have the restricted bucket name handy.

:param account_id: user account ID
:type account_id: str
:param auth_token: user authentication token
:type auth_token: str
:param api_url: an API URL
:type api_url: str
:param download_url: path download URL
:type download_url: str
:param minimum_part_size: minimum size of the file part
:type minimum_part_size: int
:param application_key: application key
:type application_key: str
:param realm: a realm to authiroze account in
:type realm: str
:param allowed: the structure to use for old account info that was saved without 'allowed'
:type allowed: dict
:param account_id_or_app_key_id: account ID or application key ID
:type account_id_or_app_key_id: str
"""
if allowed is None:
allowed = self.DEFAULT_ALLOWED
Expand All @@ -173,6 +247,10 @@ def allowed_is_valid(cls, allowed):

If the bucketId is for a bucket that no longer exists, or the
capabilities do not allow listBuckets, then we won't have a bucketName.

:param allowed: the structure to use for old account info that was saved without 'allowed'
:type allowed: dict
:rtype: bool
"""
return (
('bucketId' in allowed) and ('bucketName' in allowed) and
Expand Down Expand Up @@ -203,6 +281,10 @@ def take_bucket_upload_url(self, bucket_id):
Returns a pair (upload_url, upload_auth_token) that has been removed
from the pool for this bucket, or (None, None) if there are no more
left.

:param bucket_id: a bucket ID
:type bucket_id: str
:rtype: tuple
"""

@abstractmethod
Expand All @@ -211,17 +293,47 @@ def put_bucket_upload_url(self, bucket_id, upload_url, upload_auth_token):
"""
Add an (upload_url, upload_auth_token) pair to the pool available for
the bucket.

:param bucket_id: a bucket ID
:type bucket_id: str
:param upload_url: an upload URL
:type upload_url: str
:param upload_auth_token: an upload authentication token
:type upload_auth_token: str
:rtype: tuple
"""

@abstractmethod
@limit_trace_arguments(only=['self'])
def put_large_file_upload_url(self, file_id, upload_url, upload_auth_token):
"""
Put large file upload URL into a pool

:param file_id: a file ID
:type file_id: str
:param upload_url: an upload URL
:type upload_url: str
:param upload_auth_token: an upload authentication token
:type upload_auth_token: str
"""
pass

@abstractmethod
def take_large_file_upload_url(self, file_id):
"""
Take large file upload URL from a pool

:param file_id: a file ID
:type file_id: str
"""
pass

@abstractmethod
def clear_large_file_upload_urls(self, file_id):
"""
Clear a pool of URLs for a given file ID

:param file_id: a file ID
:type file_id: str
"""
pass
Loading