diff options
-rw-r--r-- | README.rst | 52 |
1 files changed, 48 insertions, 4 deletions
@@ -20,10 +20,54 @@ Keys or passwords for Pandora are **not** provided in this repo, you'll have to | |||
20 | for yourself. Make something awesome with this library, don't abuse Pandora, | 20 | for yourself. Make something awesome with this library, don't abuse Pandora, |
21 | that's not cool. | 21 | that's not cool. |
22 | 22 | ||
23 | The easy entry-point for programmatic use is | 23 | As of 1.11.0 users of Python 3.4+ no longer require a native dependency and can |
24 | ``pandora.clientbuilder.PydoraConfigFileBuilder``. All programmatic APIs are in | 24 | use this package in its pure Python form. Users of older versions of Python |
25 | the ``pandora`` package. The remainder of this README is targeted at users of | 25 | will require `cryptography <https://pypi.python.org/pypi/cryptography>`_. This |
26 | the ``pydora`` command-line player. | 26 | is configured automatically when pydora is installed. |
27 | |||
28 | Programatic Use | ||
29 | =============== | ||
30 | The pydora distribution contains two python packages. The ``pandora`` package | ||
31 | is the API for interacting with the Pandora service. The ``pydora`` package is | ||
32 | a very small reference implementation of using the API to drive a command line | ||
33 | player. If you're interested in the command line skip this section and read | ||
34 | Installing below to get started. | ||
35 | |||
36 | **NOTE:** This package uses semantic versioning. The API is stable within a | ||
37 | major version release. Please constrain your dependencies to major versions. | ||
38 | For example, to depend on version 1.x use this line in your setup.py | ||
39 | ``install_requires``:: | ||
40 | |||
41 | pydora>=1,<2 | ||
42 | |||
43 | The easiest way to get started is by using the ``pandora.clientbuilder`` | ||
44 | package. This package contains a set of factories that can be used to build a | ||
45 | Pandora client with some configuration. The classes in the package that end in | ||
46 | ``Builder`` are the factories and the rest of the classes are implementation | ||
47 | details. All of the builders will return an instance of | ||
48 | ``pandora.client.APIClient`` that is completely configured and ready for use in | ||
49 | your program. | ||
50 | |||
51 | If you have an existing program and would like to connect to Pandora the | ||
52 | easiest way is to use the ``SettingsDictBuilder`` class like so:: | ||
53 | |||
54 | client = SettingsDictBuilder({ | ||
55 | "DECRYPTION_KEY": "see_link_above", | ||
56 | "ENCRYPTION_KEY": "see_link_above", | ||
57 | "PARTNER_USER": "see_link_above", | ||
58 | "PARTNER_PASSWORD": "see_link_above", | ||
59 | "DEVICE": "see_link_above", | ||
60 | }).build() | ||
61 | |||
62 | client.login("username", "password") | ||
63 | |||
64 | At this point the client is ready for use, see ``pandora.client.APIClient`` for | ||
65 | a list of methods that can be called. All responses from the API will return | ||
66 | Python objects from the ``pandora.models.pandora`` package or raise exceptions | ||
67 | from ``pandora.errors`` | ||
68 | |||
69 | For a more functional example look at the file ``pydora/player.py`` which shows | ||
70 | how to use the API in a simple command line application. | ||
27 | 71 | ||
28 | Installing | 72 | Installing |
29 | ========== | 73 | ========== |