[diaspy.git] / README.md

## Unofficial Python interface for Diaspora\* social network

[![Diaspy on PyPI](https://badge.fury.io/py/diaspy-api.png)](https://pypi.python.org/pypi/diaspy-api)

`diaspy` is a set of modules which form an Python interface to the API of
Diaspora\* social network. 

Test suite will cause problems when run with 2.x so testing should be done 
using python3 interpreter.

Object oriented design of `diaspy` makes it easily reusable by other 
developers who want to use only part of the interface and create derivative
works from it.

Developers who don't like the design of `diaspy` and want to create something better
can use only `diaspy.connection.Connection()` object as it is capable of
doing everything. Other modules are just layers that provide easier access to
parts of the Diaspora\* API.

----

### Dependencies

List of software `diaspy` requires to run.
Versions used by maintainer are the ones available in stock Arch x86\_64 repositories.

**`python`**

Version: 3.3.3
[Website](https://www.python.org/)


**`python-requests`**

Version: 2.1.0
[Website](http://docs.python-requests.org/en/latest/)

**`python-dateutil`**

Version: >= 2.2
[Website](https://github.com/dateutil/dateutil)

*Optional:* **`python-beautifulsoup4`**
[Website](https://www.crummy.com/software/BeautifulSoup/)


----

#### Quick intro

#### 1. Posting text to your stream

You only need two objects to do this: `Stream()` and `Connection()`. 

    >>> import diaspy
    >>> c = diaspy.connection.Connection(pod='https://pod.example.com',
    ...                                  username='foo',
    ...                                  password='bar')
    >>> c.login()
    >>> stream = diaspy.streams.Stream(c)
    >>> stream.post('Your first post')

----

#### 2. Reference implementation

There is no official reference implementation of D\* client using `diaspy`.
The `diaspy.client` module is no longer maintained and will be removed in the future.

However, there is a small script written that uses `diaspy` as its backend.
Look for `diacli` in marekjm's repositories on GitHub.

----

To get more information about how the code works read 
documentation (`./doc/` directory) and manual (`./manual/` directory).
Commit	Line	Data
74edacee	1	## Unofficial Python interface for Diaspora\* social network
9cd5e2bd	2
dead87b6 MM	3	[![Diaspy on PyPI](https://badge.fury.io/py/diaspy-api.png)](https://pypi.python.org/pypi/diaspy-api)
dead87b6 MM	4
9cd5e2bd	5	`diaspy` is a set of modules which form an Python interface to the API of
766e6e70	6	Diaspora\* social network.
f2eaa3c7	7
c8b0cc01 MM	8	Test suite will cause problems when run with 2.x so testing should be done
c8b0cc01 MM	9	using python3 interpreter.
f2eaa3c7 MM	10
f2eaa3c7 MM	11	Object oriented design of `diaspy` makes it easily reusable by other
9cd5e2bd MM	12	developers who want to use only part of the interface and create derivative
	13	works from it.
	14
766e6e70	15	Developers who don't like the design of `diaspy` and want to create something better
9cd5e2bd MM	16	can use only `diaspy.connection.Connection()` object as it is capable of
	17	doing everything. Other modules are just layers that provide easier access to
	18	parts of the Diaspora\* API.
f2eaa3c7	19
74edacee MM	20	----
	21
	22	### Dependencies
	23
	24	List of software `diaspy` requires to run.
	25	Versions used by maintainer are the ones available in stock Arch x86\_64 repositories.
	26
	27	`python`
	28
	29	Version: 3.3.3
	30	[Website](https://www.python.org/)
	31
	32
	33	`python-requests`
	34
	35	Version: 2.1.0
	36	[Website](http://docs.python-requests.org/en/latest/)
	37
914307f2 C	38	`python-dateutil`
	39
	40	Version: >= 2.2
	41	[Website](https://github.com/dateutil/dateutil)
	42
	43	Optional: `python-beautifulsoup4`
	44	[Website](https://www.crummy.com/software/BeautifulSoup/)
	45
74edacee	46
f2eaa3c7 MM	47	----
	48
	49	#### Quick intro
	50
	51	#### 1. Posting text to your stream
	52
	53	You only need two objects to do this: `Stream()` and `Connection()`.
	54
	55	>>> import diaspy
	56	>>> c = diaspy.connection.Connection(pod='https://pod.example.com',
	57	... username='foo',
	58	... password='bar')
	59	>>> c.login()
5c03fee4	60	>>> stream = diaspy.streams.Stream(c)
f2eaa3c7 MM	61	>>> stream.post('Your first post')
f2eaa3c7 MM	62
74edacee	63	----
f2eaa3c7	64
9cd5e2bd MM	65	#### 2. Reference implementation
	66
	67	There is no official reference implementation of D\* client using `diaspy`.
	68	The `diaspy.client` module is no longer maintained and will be removed in the future.
f2eaa3c7	69
9cd5e2bd MM	70	However, there is a small script written that uses `diaspy` as its backend.
9cd5e2bd MM	71	Look for `diacli` in marekjm's repositories on GitHub.
f2eaa3c7 MM	72
	73	----
	74
	75	To get more information about how the code works read
	76	documentation (`./doc/` directory) and manual (`./manual/` directory).