Skip to main content

Platform@Mail.ru Python REST API wrapper

Project description

Platform@Mail.Ru Python REST API wrapper

About

This is a my.mail.ru (Russian social network) python API wrapper. The main features are:

  • support of REST API methods
  • extra methods (scrapers) based on REST API methods

Getting Started

Install package using pip

pip install aiomailru

REST API

To use Platform@Mail.Ru API you need a registered app and Mail.Ru account:

  1. Sign up in Mail.Ru.
  2. Create standalone application.
  3. Save client_id (aka app_id), private_key, secret_key (aka app_secret).
  4. Use app_id, list of required permissions and user credentials to get session_key (aka access_token).
  5. Use the access token to make method requests.

After signing up visit the Platform@Mail.Ru REST API documentation page and create a new standalone application: https://api.mail.ru/apps/my/add

app_id = 'your_client_id'
private_key = 'your_private_key'
secret_key = 'your_secret_key'

ImplicitSession

You can authenticate with Platform@Mail.Ru OAuth2 by passing user credentials and permissions

from aiomailru.utils import full_scope

email = 'user_email'
password = 'user_password'
scope = full_scope()

to ImplicitSession

from aiomailru.sessions import ImplicitSession

session = await ImplicitSession(
        app_id=app_id,
        private_key=private_key,
        secret_key=secret_key,
        email=email,
        passwd=password,
        scope=scope,
)

List of all permissions is available here: https://api.mail.ru/docs/guides/restapi/#permissions.

Now you can make requests (See. Making API request). After authentication you will get session key session.session_key and user ID session.uid. Save them to make requests later.

access_token = session.session_key
uid = session.uid
cookies = session.cookies

Cookies are required for scraping. See Scrapers.

TokenSession

If you already have an access token and either of two:

  • uid and private_key
  • secret_key
from aiomailru.sessions import TokenSession
session = TokenSession(
    app_id=app_id,
    private_key=private_key,
    secret_key=secret_key,
    access_token=access_token,
    uid=uid,
)

you can instantiate TokenSession and make requests.

Making API request

List of all methods is available here: https://api.mail.ru/docs/reference/rest/

from aiomailru import API
api = API(session)

# current user's friends
friends = await api.friends.get()

# events for current user
events = await api.strream.get()

List of some objects is available here: ./docs/objects.md

Under the hood each API request is enriched with:

to authorize request.

By default, the session tries to inference which signature circuit to use:

You can explicitly choose a circuit for signing requests by passing to API one of the following sessions:

Client-Server circuit
from aiomailru import ImplicitClientSession, API
session = await ImplicitClientSession(app_id, private_key, email, password, scope)
api = API(session)

or if you already have an access token

from aiomailru import ClientSession, API
session = ClientSession(app_id, private_key, access_token, uid)
api = API(session)
Server-server circuit
from aiomailru import ImplicitServerSession, API
session = await ImplicitServerSession(app_id, secret_key, email, password, scope)
api = API(session)

or if you already have an access token

from aiomailru import ServerSession, API
session = ServerSession(app_id, secret_key, access_token)
api = API(session)

Scrapers

The following scrapers are available:

  • groups.get
  • groups.getInfo
  • groups.join
  • stream.getByAuthor
from aiomailru.scrapers import APIScraper

api = APIScraper(session)

# current user's groups
groups = await api.groups.get()

Scrapers have the following requirements:

Cookies

If session is instance of TokenSession you must set cookies that were given by ImplicitSession:

session = ServerSession(app_id, secret_key, access_token, cookies=cookies)

Pyppeteer

Scrapers require an instance of Chrome.

You can start a new Chrome process:

from aiomailru.scrapers import APIScraper
from pyppeteer import launch

browser = await launch()
api = APIScraper(session, browser=browser)

print(browser.wsEndpoint)  # your browser's endpoint

or connect to the existing Chrome:

from aiomailru.scrapers import APIScraper
from pyppeteer import connect

browser_conn = {'browserWSEndpoint': 'your_endpoint'}
browser = await connect(browser_conn)
api = APIScraper(session, browser=browser)

Export environment variable

export PYPPETEER_BROWSER_ENDPOINT='your_endpoint'

to automatically connect to Chrome:

from aiomailru.scrapers import APIScraper

api = APIScraper(session)  # connects to PYPPETEER_BROWSER_ENDPOINT

Browserless

You can replace pyppeteer.launch with pyppeteer.connect. See https://www.browserless.io

Start headless chrome using

docker-compose up -d chrome

Export environment variable

export PYPPETEER_BROWSER_ENDPOINT=ws://localhost:3000

to automatically connect to Browserless container:

from aiomailru.scrapers import APIScraper

api = APIScraper(session)  # connects to ws://localhost:3000

License

aiomailru is released under the BSD 2-Clause License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aiomailru-0.0.12.tar.gz (16.7 kB view hashes)

Uploaded Source

Built Distribution

aiomailru-0.0.12-py3-none-any.whl (18.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page