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:
- Sign up in Mail.Ru.
- Create standalone application.
- Save client_id (aka app_id), private_key, secret_key (aka app_secret).
- Use app_id, list of required permissions and user credentials to get session_key (aka access_token).
- 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:
uidandprivate_keysecret_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:
- the set of required parameters
(https://api.mail.ru/docs/guides/restapi/#params):
methodapp_idsig(https://api.mail.ru/docs/guides/restapi/#sig)
session_keyuidif necessarysecureif necessary
By default, the session tries to inference which signature circuit to use:
- if
uidandprivate_keyare not empty strings - client-server signature circuit is used https://api.mail.ru/docs/guides/restapi/#client - else if
secret_keyis not an empty string - server-server signature circuit is used https://api.mail.ru/docs/guides/restapi/#server - else exception is raised
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.getgroups.getInfogroups.joinstream.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.