Skip to main content

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.

Metadata

Release files for aiomailru 0.0.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiomailru 0.0.12
File Size Uploaded Provenance Actions
aiomailru-0.0.12.tar.gz 16.7 kB Without provenance Details for aiomailru-0.0.12.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiomailru 0.0.12
File Interpreter ABI Platform Actions
aiomailru-0.0.12-py3-none-any.whl Python 3 none any Details for aiomailru-0.0.12-py3-none-any.whl

Total release size: 34.7 kB

Release files / aiomailru-0.0.12.tar.gz

Download URL aiomailru-0.0.12.tar.gz
Size 16.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3a073be8cc739b3cc590d15641d2a76f664cd601ee324c2db4eb36ac7be7323e
BLAKE2b-256 checksum
How to use checksums
9aa96b9f0c964ee3900abcf4fc9f9a267852e182374dd7d73ba67749ea088760
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.7.2

Release files / aiomailru-0.0.12-py3-none-any.whl

Download URL aiomailru-0.0.12-py3-none-any.whl
Size 18.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
81ee00a2032b304230f34fbf24f5d95e4654e875467285e7267efc8f6f2faec3
BLAKE2b-256 checksum
How to use checksums
7adb6f0e8352f9cdeae52aa9049867e7fb2de09a62ac67355f70f7ea116cfe72
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.7.2

Security for aiomailru 0.0.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page