From 51b935b5a5034ac54333c2913950f654a470e301 Mon Sep 17 00:00:00 2001 From: 9seconds Date: Tue, 26 Aug 2014 23:09:53 +0400 Subject: [PATCH 1/6] Rename documentation from md to rst --- README.md => README.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README.md => README.rst (100%) diff --git a/README.md b/README.rst similarity index 100% rename from README.md rename to README.rst From 1150bd856fae4620161c827505b698e070cc7c4e Mon Sep 17 00:00:00 2001 From: 9seconds Date: Tue, 26 Aug 2014 23:27:35 +0400 Subject: [PATCH 2/6] Convert Markdown to RST --- README.rst | 124 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 87 insertions(+), 37 deletions(-) diff --git a/README.rst b/README.rst index 09a4eb8..dbfdcbd 100644 --- a/README.rst +++ b/README.rst @@ -1,67 +1,86 @@ +btsync.py +========= - ____ ______ _____ __ __ ____ __ ____ __ __ +|Build Status| |Coverage Status| + +:: + + ____ ______ _____ __ __ ____ __ ____ __ __ | \ | |/ ___/| | || \ / ] | \| | | | o )| ( \_ | | || _ | / / | o ) | | | ||_| |_|\__ || ~ || | |/ / | _/| ~ | | O | | | / \ ||___, || | / \_ __ | | |___, | | | | | \ || || | \ || || | | | - |_____| |__| \___||____/ |__|__|\____||__||__| |____/ - + |_____| |__| \___||____/ |__|__|\____||__||__| |____/ -[![Build Status](https://travis-ci.org/kevinjqiu/btsync.py.png?branch=master)](https://travis-ci.org/kevinjqiu/btsync.py) -[![Coverage Status](https://coveralls.io/repos/kevinjqiu/btsync.py/badge.png?branch=master)](https://coveralls.io/r/kevinjqiu/btsync.py?branch=master) A Python API client for BitTorrent Sync + Installation -============ +------------ + +Install from `PyPI `__: -Install from [PyPI](https://pypi.python.org): +.. code-block:: bash - pip install btsync.py + $ pip install btsync.py Or Install from source: - git clone git@github.com:kevinjqiu/btsync.py.git - cd btsync.py - pip install -r requirements.txt - python setup.py install +.. code-block:: bash + + $ git clone git@github.com:kevinjqiu/btsync.py.git + $ cd btsync.py + $ pip install -r requirements.txt + $ python setup.py install + + Examples -======== +-------- + +You need to first download `btsync `__ for your platform. +Once it's downloaded, extract it somewhere and generate a sample config file: -You need to first download [btsync](http://labs.bittorrent.com/experiments/sync/get-started.html) for your platform. Once it's downloaded, extract it somewhere and generate a sample config file: +.. code-block:: bash - cd /path/to/btsync - ./btsync --dump-sample-config > config + $ cd /path/to/btsync + $ ./btsync --dump-sample-config > config Change the default config if you wish. The pieces of config you need for the client to connect are: + - host - port (listening port) - username - password -Run `btsync` with the config: +Run ``btsync`` with the config: + +.. code-block:: bash - ./btsync --config config + $ ./btsync --config config With btsync running, now you can connect to it using this library: Creating a client: - In [1]: import btsync +.. code-block:: python - In [2]: client = btsync.Client( - ...: host='127.0.0.1', - ...: port='1106', - ...: username='admin', - ...: password='password') + >>> import btsync + >>> client = btsync.Client( + ... host='127.0.0.1', + ... port='1106', + ... username='admin', + ... password='password') Listing sync folders: - In [3]: client.sync_folders - Out[3]: +.. code-block:: python + + >>> import pprint + >>> pprint.pprint(client.sync_folders) [{u'iswritable': 1, u'name': u'/home/foo/bar', u'peers': [{u'direct': 1, @@ -79,19 +98,20 @@ Listing sync folders: Generate a secret for adding a sync folder: - In [7]: secret = client.generate_secret() +.. code-block:: python - In [8]: secret - Out[8]: + >>> secret = client.generate_secret() + >>> pprint.pprint(secret) {u'rosecret': u'--------------------------------', u'secret': u'--------------------------------'} Add a sync folder: - In [10]: client.add_sync_folder('/tmp', secret['rosecret']) +.. code-block:: python + + >>> client.add_sync_folder('/tmp', secret['rosecret']) - In [11]: client.sync_folders[1] - Out[11]: + >>> pprint.pprint(client.sync_folders[1]) {u'iswritable': 0, u'name': u'/tmp', u'peers': [], @@ -99,52 +119,82 @@ Add a sync folder: u'size': u'0 B in 0 files'} + Development -=========== +----------- First, you need to setup a virtualenv, as it segregates local dependencies from the system libraries nicely: +.. code-block:: bash + $ virtualenv btsync.py-env Activate the virtual environment: +.. code-block:: bash + $ cd btsync.py-env $ . btsync.py-env/bin/activate -Clone this repo somewhere, e.g., `$HOME/src/btsync.py`: +Clone this repo somewhere, e.g., ``$HOME/src/btsync.py``: + +.. code-block:: bash $ git clone git@github.com:kevinjqiu/btsync.py.git $ cd btsync.py Install dev dependencies: +.. code-block:: bash + $ pip install -r requirements-dev.txt Run tests: +.. code-block:: bash + $ fab test You can also generate the coverage report: +.. code-block:: bash + $ fab coverage -To run integration tests, you need to have `btsync` executable on your `$PATH`: +To run integration tests, you need to have ``btsync`` executable on your ``$PATH``: + +.. code-block:: bash $ fab test_integration -Optionally, you can set an environment variable `BTSYNC` before running the test: +Optionally, you can set an environment variable ``BTSYNC`` before running the test: + +.. code-block:: bash $ BTSYNC=$HOME/btsync/btsync fab test_integration To run coverage for integration tests: +.. code-block:: bash + $ fab coverage:integration You can also change the port the btsync instance for integration test runs on (the default port is 59999): +.. code-block:: bash + $ BTSYNC_PORT=55555 fab test_integration + + License ======= -See [LICENSE](license.txt) +See `LICENSE `__. + + +.. |Build Status| .. image:: https://travis-ci.org/kevinjqiu/btsync.py.svg?branch=master + :target: https://travis-ci.org/kevinjqiu/btsync.py + +.. |Coverage Status| image:: https://coveralls.io/repos/kevinjqiu/btsync.py/badge.png?branch=master + :target: https://coveralls.io/r/kevinjqiu/btsync.py?branch=master From bb659a4ee00ca8307d7dfc90faab2502a951ea34 Mon Sep 17 00:00:00 2001 From: 9seconds Date: Tue, 26 Aug 2014 23:28:54 +0400 Subject: [PATCH 3/6] Fix for build status badge code --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index dbfdcbd..6f2696f 100644 --- a/README.rst +++ b/README.rst @@ -193,7 +193,7 @@ License See `LICENSE `__. -.. |Build Status| .. image:: https://travis-ci.org/kevinjqiu/btsync.py.svg?branch=master +.. |Build Status| image:: https://travis-ci.org/kevinjqiu/btsync.py.svg?branch=master :target: https://travis-ci.org/kevinjqiu/btsync.py .. |Coverage Status| image:: https://coveralls.io/repos/kevinjqiu/btsync.py/badge.png?branch=master From 5741aad8ddd7080c6a11dfd70b08ed28954d8817 Mon Sep 17 00:00:00 2001 From: 9seconds Date: Tue, 26 Aug 2014 23:29:42 +0400 Subject: [PATCH 4/6] Use RST documentation by default --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index d76e830..58cd5f7 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ setup(name='btsync.py', version=version, description="A Python API client for BitTorrent Sync", - long_description=open('README.md').read(), + long_description=open('README.rst').read(), classifiers=[ 'Intended Audience :: Developers', 'Environment :: Console', From efce482db1dfb13c1f221683867dcbfb50525985 Mon Sep 17 00:00:00 2001 From: 9seconds Date: Tue, 26 Aug 2014 23:35:10 +0400 Subject: [PATCH 5/6] Remove excess empty line --- README.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/README.rst b/README.rst index 6f2696f..55534a9 100644 --- a/README.rst +++ b/README.rst @@ -110,7 +110,6 @@ Add a sync folder: .. code-block:: python >>> client.add_sync_folder('/tmp', secret['rosecret']) - >>> pprint.pprint(client.sync_folders[1]) {u'iswritable': 0, u'name': u'/tmp', From dd263b0b4caec60e8279c69ebb8e671a4861cf53 Mon Sep 17 00:00:00 2001 From: 9seconds Date: Wed, 27 Aug 2014 07:14:46 +0400 Subject: [PATCH 6/6] Fixes for the build --- MANIFEST.in | 2 +- setup.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/MANIFEST.in b/MANIFEST.in index 34a9459..d263aa7 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,3 @@ -include README.md +include README.rst include LICENSE include *.txt diff --git a/setup.py b/setup.py index 58cd5f7..33c4d44 100644 --- a/setup.py +++ b/setup.py @@ -21,7 +21,7 @@ url='https://github.com/kevinjqiu/btsync.py', license='MIT', packages=find_packages(exclude=['ez_setup', 'examples', 'tests']), - data_files=[('.', ['requirements.txt', 'README.md', 'LICENSE'])], + data_files=[('.', ['requirements.txt', 'README.rst', 'LICENSE'])], include_package_data=True, zip_safe=False, install_requires=open('requirements.txt').readlines(),