Metadata-Version: 2.1
Name: aiookru
Version: 0.0.1
Summary: ok.ru Python REST API wrapper
Home-page: https://github.com/KonstantinTogoi/aiookru
Author: Konstantin Togoi
Author-email: konstantin.togoi@protonmail.com
License: BSD
Description: # ok.ru Python REST API wrapper
        
        - [About](#about)
        - [Getting Started](#getting-started)
            + [ImplicitSession](#implicitsession)
            + [TokenSession](#tokensession)
            + [Executing API requests](#executing-api-requests)
                - [Client-Server signature circuit](#client-server-circuit)
                - [Server-Server signature circuit](#sever-server-circuit)
        - [License](#license)
        
        
        ## About
        
        This is [ok.ru](https://ok.ru) (Russian social network) python API wrapper.
        The goal is to support all API methods: https://apiok.ru/en/dev/methods/rest.
        
        ## Getting Started
        
        Install package using pip
        
        ```bash
        pip install aiookru
        ```
        
        To use OK API you need a registered app and account in the social network.
        
        1. Sign up in [ok.ru](https://ok.ru)
        2. Create **external** application.
        3. Save **App ID**, **App key**, **App secret key**.
        4. Use App ID, list of required permissions and user credentials to get **access token**.
        5. Use the access token to make method requests.
        
        After signing up go to https://apiok.ru/en/dev/app/create and create application.
        
        ```python
        app_id = 'app ID'
        app_key = 'app key'
        app_secret_key = 'app secret'
        ```
        
        ### ImplicitSession
        
        You can authenticate with [OK API OAuth](https://apiok.ru/en/ext/oauth/) by passing user credentials and permissions to `ImplicitSession` (or `ImplicitClientSession`/
        `ImplicitServerSession`).
        
        ```python
        from aiookru.sessions import ImplicitSession
        
        phone = '+1999123456'
        password = 'user password'
        
        session = await ImplicitSession(
            app_id=app_id,
            app_key=app_key,
            app_secret_key=app_secret_key,
            login=phone,
            passwd=password,
            permissions='VALUABLE_ACCESS',
        )
        ```
        
        Now you can execute API requests (see [Executing API requests](#executing-api-requests)).
        After authentication you will get access token **session.access_token** and
        session secret key **session.session_secret_key**. Save them to make requests later:
        
        ```python
        access_token = session.access_token
        session_secret_key = session.session_secret_key
        ```
        
        ### TokenSession
        
        If you already have either of two:
        
        - `app_secret_key` and `access_token`
        - `session_secret_key`
        
        ```python
        from aiookru.sessions import TokenSession
        
        session = TokenSession(
            app_key=app_key,
            app_secret_key=app_secret_key,
            access_token=access_token,
            session_secret_key=session_secret_key,
        )
        ```
        
        you can instantiate `TokenSession` (or `ClinentSession`/`ServerSession`) and execute requests.
        
        
        ### Executing API requests
        
        ```python
        from aiookru import API
        
        api = API(session)
        
        # current user's friends
        friends = await api.friends.get()
        ```
        
        Under the hood each API requests is encriched with:
        
        - `application_key`
        - `sig`
        - `app_secret_key` and `access_token` or `session_secret_key` 
        - `format`
        - `method`
        
        By default, the sessions try to infer which signature circuit to use:
        
        - if `app_secret_key` and `access_token` are not empty strings - server-server signature circuit is used
        - else if `session_secret_key` is not empty string - client-server signature circuit is used
        - else exception is raised
        
        You can explicitly choose a circuit for signing requests by passing to `API` one
        of the following sessions:
        
        #### Sever-Server circuit
        
        ```python
        from aiookru import ImplicitServerSession, API
        session = await ImplicitServerSession(app_id, app_key, app_secret_key, phone, password)
        api = API(session)
        ```
        
        or if you already have an access token
        
        ```python
        from aiookru import ServerSession, API
        session = ServerSession(app_key, app_secret_key, access_token)
        ```
        
        #### Client-Server circuit
        
        ```python
        from aiookru import ImplicitClientSession, API
        session = await ImplicitClientSession(app_id, app_key, phone, password)
        api = API(session)
        ```
        
        or if you already have a session secret key
        
        ```python
        from aiookru import ClientSession, API
        session = await ClientSession(app_key, session_secret_key)
        api = API(session)
        ```
        
        ## License
        
        **aiookru** is released under the BSD 2-Clause License.
        
Keywords: ok.ru api asyncio
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
