You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
This repository contains a client library and a few handy utilities for easy access to all of the capabilities of B2 Cloud Storage.
4
4
5
-
[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).
5
+
[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).
.. caution:: Correct version pinning is necessary to make sure your code remains compatible with upcoming b2sdk releases.
12
+
13
+
See :ref:`this <semver>` chapter for details.
14
+
15
+
Installing for development
16
+
~~~~~~~~~~~~~~~~~~~~~~~~~~
17
+
8
18
B2 SDK runs on Python 2.7+ under CPython and PyPy.
9
19
10
-
To install B2 SDK run::
20
+
To install B2 SDK, simply run::
11
21
12
22
pip install b2sdk
13
23
14
-
If you see a message saying that the `six` library cannot be installed, which
15
-
happens if you're installing with the system python on OS X El Capitan, try
16
-
this::
24
+
In your python environment.
25
+
26
+
.. note:: If you see a message saying that the ``six`` library cannot be installed, which
27
+
happens if you're installing with the system python on OS X El Capitan, try this::
28
+
29
+
pip install --ignore-installed b2sdk
17
30
18
-
pip install --ignore-installed b2sdk
19
31
20
32
Developer Info
21
33
==============
@@ -27,7 +39,7 @@ We encourage outside contributors to perform changes on our codebase. Many such
27
39
* maintain a set of integration tests (run with a production cloud)
28
40
* maintain a set of (well over a hundred) unit tests
29
41
* automatically run unit tests on 14 versions of python (including osx, Jython and pypy)
30
-
* format the code automatically using [yapf](https://github.com/google/yapf)
42
+
* format the code automatically using `yapf<https://github.com/google/yapf>`_
31
43
* use static code analysis to find subtle/potential issues with maintainability
32
44
* maintain other Continous Integration tools (coverage tracker)
33
45
@@ -42,17 +54,17 @@ There is a `Makefile` with a rule to run the unit tests using the currently acti
42
54
43
55
will install the required packages, then run the unit tests.
44
56
45
-
To test in multiple python virtual environments, set the enviroment variable `PYTHON_VIRTUAL_ENVS`
57
+
To test in multiple python virtual environments, set the enviroment variable ``PYTHON_VIRTUAL_ENVS``
46
58
to be a space-separated list of their root directories. When set, the makefile will run the
47
59
unit tests in each of the environments.
48
60
49
-
Before checking in, use the `pre-commit.sh` script to check code formatting, run
61
+
Before checking in, use the ``pre-commit.sh`` script to check code formatting, run
50
62
unit tests, run integration tests etc.
51
63
52
-
The integration tests need a file in your home directory called `.b2_auth`
64
+
The integration tests need a file in your home directory called ``.b2_auth``
53
65
that contains two lines with nothing on them but your account ID and application key::
54
66
55
67
accountId
56
68
applicationKey
57
69
58
-
We marked the places in the code which are significantly less intuitive than others in a special way. To find them occurrences, use `git grep '*magic*'`.
70
+
We marked the places in the code which are significantly less intuitive than others in a special way. To find them occurrences, use ``git grep '*magic*'``.
b2sdk is divided into three parts. Please pay attention to which group you use, as the stability of your application depends on correct pinning of versions.
12
+
13
+
++++++++++
14
+
Interfaces
15
+
++++++++++
16
+
17
+
Public
18
+
======
19
+
20
+
Public interface consists of *public* members of the following modules:
21
+
22
+
.. autosummary::
23
+
:nosignatures:
24
+
25
+
b2sdk.api.B2Api
26
+
b2sdk.bucket.Bucket
27
+
b2sdk.exception
28
+
b2sdk.sync
29
+
b2sdk.sync.exception
30
+
b2sdk.account_info.abstract
31
+
b2sdk.account_info.exception
32
+
b2sdk.account_info.sqlite_account_info
33
+
b2sdk.account_info.upload_url_pool
34
+
b2sdk.transferer
35
+
b2sdk.utils
36
+
37
+
Those will not change in a backwards-incompatible way between non-major versions. In other words, if you pin your dependencies to `>=x.0.0;<x+1.0.0`, everything should be ok.
38
+
In other words, if you pin your dependencies to
39
+
40
+
.. hint:: If the current version of b2sdk is 4.5.6 and you only use the public interfaces, put this in your requirements.txt::
41
+
42
+
>=4.5.6;<5.0.0
43
+
44
+
.. note:: b2sdk.*._something and b2sdk.*.*._something, having a name which begins with an underscore, are NOT considred public interface.
45
+
46
+
47
+
Protected
48
+
=========
49
+
50
+
Things which sometimes might be necssary to use that are NOT considered public interface (and may change in a non-major version):
51
+
52
+
.. autosummary::
53
+
:nosignatures:
54
+
55
+
b2sdk.session.B2Session
56
+
b2sdk.raw_api.B2RawApi
57
+
b2sdk.b2http.B2Http
58
+
59
+
.. note:: it is ok for you to use those (better that, than copying our sources), however if you do, please pin your dependencies to middle version.
60
+
61
+
.. hint:: If the current version of b2sdk is 4.5.6 and you use the public and protected interfaces, put this in your requirements.txt::
62
+
63
+
>=4.5.6;<4.6.0
64
+
65
+
66
+
Private
67
+
=======
68
+
69
+
If you need to use some of our private interfaces, pin your dependencies strictly.
70
+
71
+
.. hint:: If the current version of b2sdk is 4.5.6 and you use the private interface, put this in your requirements.txt::
72
+
73
+
==4.5.6
74
+
75
+
*************
76
+
Authorization
77
+
*************
78
+
79
+
Before you can use b2sdk, you need to prove who you are to the server. For that you will need to pass `account id` and `api token` to one of the authorization classes.
80
+
81
+
In case you are storing that information in a database or something, you can implement your own class by inheriting from AbstractAuthorization. Otherwise, use one of the classes included in b2sdk package:
82
+
83
+
84
+
InMemoryAccountInfo:
85
+
86
+
This is probably what your application should be using and also what we use in our tests.
87
+
88
+
89
+
SqliteAccountInfo:
90
+
91
+
this is what B2 CLI uses to authorize the user. Stores information in a local file.
92
+
93
+
94
+
B2Api
95
+
~~~~~
96
+
97
+
The "main" object that abstracts the communication with B2 cloud is B2Api. It lets you manage buckets and download files by id.
98
+
99
+
example
100
+
101
+
102
+
Bucket
103
+
~~~~~~
104
+
105
+
Bucket class abstracts the B2 bucket, which is essentially a namespace for objects.
106
+
107
+
The best way to transfer your files into a bucket and back, is to use *sync*.
108
+
109
+
If for some reason you cannot use sync, it is also possible to upload and download files directly into/from the bucket, using Bucket.upload_file and Bucket.download_by_name.
110
+
111
+
The Bucket object also contains a few methods to list the contents of the bucket and the metadata associated with the objects contained in it.
0 commit comments