bump version to 0.1.1

README.rst

@@ -53,9 +53,9 @@ i.e. when you embed your app's info (private key) in publicly available code.
     events = await api.stream.get()
     friends = await api.friends.getOnline()
 
-Pass :code:`access_token` and :code:`uid`
+Use :code:`access_token` and :code:`uid`
 that were received after authorization. For more details, see
-`aiomailru Documentation <https://aiomailru.readthedocs.io/>`_.
+`authorization instruction <https://aiomailru.readthedocs.io/en/latest/authorization.html>`_.
 
 Server application
 ~~~~~~~~~~~~~~~~~~
@@ -75,9 +75,9 @@ Use :code:`ServerSession` when REST API is needed in:
     events = await api.stream.get()
     friends = await api.friends.getOnline()
 
-Pass :code:`access_token` that was received after authorization.
+Use :code:`access_token` that was received after authorization.
 For more details, see
-`aiomailru Documentation <https://aiomailru.readthedocs.io/>`_.
+`authorization instruction <https://aiomailru.readthedocs.io/en/latest/authorization.html>`_.
 
 Installation
 ------------

aiomailru/__init__.py

@@ -30,4 +30,4 @@
 from .api import API
 
 
-__version__ = '0.1.0.post1'
+__version__ = '0.1.1'

aiomailru/sessions.py

@@ -124,9 +124,9 @@ def cookies(self, cookies):
 
     @property
     def sig_circuit(self):
-        if self.uid and self.private_key:
+        if self.uid and self.private_key and self.app_id:
             return SignatureCircuit.CLIENT_SERVER
-        elif self.secret_key:
+        elif self.secret_key and self.app_id:
             return SignatureCircuit.SERVER_SERVER
         else:
             return SignatureCircuit.UNDEFINED

docs/source/authorization.rst

@@ -1,18 +1,14 @@
 Authorization
 =============
 
-To authorize with Mail.Ru OAuth 2.0 you need :code:`app_id`.
-And you need either :code:`private_key` or :code:`secret_key`
-for executing API requests after authorization.
-
 The preferred way to authorize is an :code:`async with` statement.
 After authorization the session will have the following attributes:
 
 * :code:`session_key` aka :code:`access_token`
-* :code:`uid` that is necessary only when :code:`secret_key` not passed
 * :code:`refresh_token`
 * :code:`expires_in`
 * :code:`token_type` if Implicit Grant used
+* :code:`uid`
 
 Authorization Code Grant
 ------------------------
@@ -22,8 +18,8 @@ Authorization Code Grant
     from aiomailru import CodeSession, API
 
     app_id = 123456
-    private_key = 'abcde'
-    secret_key = ''
+    private_key = ''
+    secret_key = 'xyz'
 
     async with CodeSession(app_id, private_key, secret_key, code, redirect_uri) as session:
         api = API(session)
@@ -42,8 +38,8 @@ Implicit Grant
     from aiomailru import ImplicitSession, API
 
     app_id = 123456
-    private_key = ''
-    secret_key = 'xyz'
+    private_key = 'abcde'
+    secret_key = ''
 
     async with ImplicitSession(app_id, private_key, secret_key, email, passwd, scope) as session:
         api = API(session)
@@ -62,7 +58,7 @@ Password Grant
 
     app_id = 123456
     private_key = 'abcde'
-    secret_key = 'xyz'
+    secret_key = ''
 
     async with PasswordSession(app_id, private_key, secret_key, email, passwd, scope) as session:
         api = API(session)
@@ -81,7 +77,7 @@ Refresh Token
 
     app_id = 123456
     private_key = ''
-    secret_key = ''
+    secret_key = 'xyz'
 
     async with RefreshSession(app_id, private_key, secret_key, refresh_token) as session:
         api = API(session)

docs/source/conf.py

@@ -22,7 +22,7 @@
 author = 'Konstantin Togoi'
 
 # The full version, including alpha/beta/rc tags
-release = '0.1.0.post1'
+release = '0.1.1'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/index.rst

@@ -17,4 +17,3 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

docs/source/rest_api.rst

@@ -6,6 +6,10 @@ List of all methods is available here: https://api.mail.ru/docs/reference/rest/.
 Executing requests
 ------------------
 
+For executing API requests call an instance of :code:`APIMethod` class.
+You can get it as an attribute of :code:`API` class instance or
+as an attribute of other :code:`APIMethod` class instance.
+
 .. code-block:: python
 
     from aiomailru import API
@@ -15,16 +19,16 @@ Executing requests
     events = await api.stream.get()  # events for current user
     friends = await api.friends.get()  # current user's friends
 
-Under the hood each API request is enriched with parameters (https://api.mail.ru/docs/guides/restapi/#params):
+Under the hood each API request is enriched with parameters to generate signature:
+
+* :code:`method`
+* :code:`app_id`
+* :code:`session_key`
+* :code:`secure`
 
-* :code:`method`, required
-* :code:`app_id`, required
-* :code:`sig`, required (https://api.mail.ru/docs/guides/restapi/#sig)
-* :code:`session_key`, required
-* :code:`uid` if necessary
-* :code:`secure` if necessary
+and with the following parameter after generating signature:
 
-to `authorize request <https://api.mail.ru/docs/guides/restapi/#session>`_.
+* :code:`sig`, see https://api.mail.ru/docs/guides/restapi/#sig
 
 Objects
 -------

docs/source/session.rst

@@ -1,44 +1,61 @@
 Session
 =======
 
+The session makes **GET** requests when you call instance of :code:`APIMethod`
+class that are returned as attributes of an :code:`API` class instance.
+
 Request
 -------
 
-The session makes **GET** requests when you call methods of an :code:`API` instance.
-Lets consider example at https://api.mail.ru/docs/guides/restapi/#client:
+By default, the session
+(:code:`CodeSession`, :code:`ImplicitSession`, :code:`PasswordSession`, :code:`RefreshSession`)
+tries to infer which signature generation circuit to use:
+
+* if :code:`uid` and :code:`private_key` are not empty strings - **client-server** signature generation circuit is used
+* else if :code:`secret_key` is not an empty string - **server-server** signature generation circuit is used
+* else exception is raised
+
+You can explicitly set a signature generation circuit for signing requests
+by passing to :code:`API` one of the sessions below.
+
+Client-Server signature generation circuit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's consider the following example of API request with client-server signature:
 
 .. code-block:: python
 
     from aiomailru import TokenSession, API
 
-    app_id = 123456
-    private_key = '7815696ecbf1c96e6894b779456d330e'
-    secret_key = ''
-    session_key = 'be6ef89965d58e56dec21acb9b62bdaa'
-    uid = '1324730981306483817'
-
-    session = TokenSession(app_id, private_key, secret_key, access_token, uid)
+    session = TokenSession(
+        app_id=423004,
+        private_key='7815696ecbf1c96e6894b779456d330e',
+        secret_key='',
+        access_token='be6ef89965d58e56dec21acb9b62bdaa',
+        uid='1324730981306483817',
+    )
     api = API(session)
 
-    events = await api.stream.get()
+    friends = await api.friends.get()
 
-is equivalent to the following **GET** request:
+It is equivalent to **GET** request:
 
 .. code-block:: shell
 
-    https://appsmail.ru/platform/api?method=stream.get&app_id=123456&session_key=be6ef89965d58e56dec21acb9b62bdaa&sig=5073f15c6d5b6ab2fde23ac43332b002
-
-By default, the session tries to infer which signature circuit to use:
+    https://appsmail.ru/platform/api
+        ?method=friends.get
+        &app_id=423004
+        &session_key=be6ef89965d58e56dec21acb9b62bdaa
+        &sig=5073f15c6d5b6ab2fde23ac43332b002
 
-* if :code:`uid` and :code:`private_key` are not empty strings - **client-server** signature circuit is used https://api.mail.ru/docs/guides/restapi/#client
-* else if :code:`secret_key` is not an empty string - **server-server** signature circuit is used https://api.mail.ru/docs/guides/restapi/#server
-* else exception is raised
+The following steps were taken:
 
-You can explicitly choose a circuit for signing requests by passing
-to :code:`API` one of the following sessions:
+1. request parameters were sorted and concatenated - :code:`app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa`
+2. :code:`uid`, sorted request parameters, :code:`private_key` were concatenated - :code:`1324730981306483817app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa7815696ecbf1c96e6894b779456d330e`
+3. signature :code:`5073f15c6d5b6ab2fde23ac43332b002` calculated as MD5 of the previous string
+4. signature appended to **GET** request parameters
 
-Client-Server signature circuit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For more details, see https://api.mail.ru/docs/guides/restapi/#client.
 
 ClientSession
 ^^^^^^^^^^^^^
@@ -105,8 +122,45 @@ RefreshClientSession
         api = API(session)
         ...
 
-Server-Server signature circuit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Server-Server signature generation circuit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's consider the following example of API request with server-server signature:
+
+.. code-block:: python
+
+    from aiomailru import TokenSession, API
+
+    session = TokenSession(
+        app_id=423004,
+        private_key='',
+        secret_key='3dad9cbf9baaa0360c0f2ba372d25716',
+        access_token='be6ef89965d58e56dec21acb9b62bdaa',
+        uid='',
+    )
+    api = API(session)
+
+    friends = await api.friends.get()
+
+It is equivalent to **GET** request:
+
+.. code-block:: shell
+
+    https://appsmail.ru/platform/api
+        ?method=friends.get
+        &app_id=423004
+        &session_key=be6ef89965d58e56dec21acb9b62bdaa
+        &sig=4a05af66f80da18b308fa7e536912bae
+
+The following steps were taken:
+
+1. parameter :code:`secure` = :code:`1` appended to parameters
+2. request parameters were sorted and concatenated - :code:`app_id=423004method=friends.getsecure=1session_key=be6ef89965d58e56dec21acb9b62bdaa`
+3. sorted request parameters and :code:`secret_key` were concatenated - :code:`1324730981306483817app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa3dad9cbf9baaa0360c0f2ba372d25716`
+4. signature :code:`4a05af66f80da18b308fa7e536912bae` calculated as MD5 of the previous string
+5. signature appended to **GET** request parameters
+
+For more details, see  https://api.mail.ru/docs/guides/restapi/#server.
 
 ServerSession
 ^^^^^^^^^^^^^
@@ -177,18 +231,23 @@ Response
 --------
 
 By default, a session after executing request returns response's body
-as :code:`dict` if executing was successful, otherwise it raises an exception.
+as :code:`dict` if executing was successful, otherwise it raises exception.
 
 You can pass :code:`pass_error` parameter to :code:`TokenSession`
 for returning original response (including errors).
 
 Error
 -----
 
-In case of an error, by default, an exception is raised.
+In case of an error, by default, exception is raised.
 You can pass :code:`pass_error` parameter to :code:`TokenSession`
 for returning original error's body as :code:`dict`:
 
 .. code-block:: python
 
-    {"error": {"error_code": 202, "error_msg": "Access to this object is denied"}}
+    {
+        "error": {
+            "error_code": 202,
+            "error_msg": "Access to this object is denied"
+        }
+    }

setup.py

@@ -3,7 +3,7 @@
 
 setup(
     name='aiomailru',
-    version='0.1.0.post1',
+    version='0.1.1',
     author='Konstantin Togoi',
     author_email='konstantin.togoi@gmail.com',
     url='https://github.com/KonstantinTogoi/aiomailru',