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 an 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.3.tar.gz (16.1 kB view details)

Uploaded Source

Built Distribution

aiomailru-0.0.3-py3-none-any.whl (17.1 kB view details)

Uploaded Python 3

File details

Details for the file aiomailru-0.0.3.tar.gz.

File metadata

  • Download URL: aiomailru-0.0.3.tar.gz
  • Upload date:
  • Size: 16.1 kB
  • Tags: Source
  • Uploaded using 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

File hashes

Hashes for aiomailru-0.0.3.tar.gz
Algorithm Hash digest
SHA256 2d0277ac036ee3190d8bec0fbcbf1919457abb84e3acbc8fc94bd13f898c747f
MD5 498265258028ad79ae204affeee968ef
BLAKE2b-256 35caac607c0317fe3ac8f847539ab67f2cd6b5083d3a592d3a0ae45685ec11aa

See more details on using hashes here.

File details

Details for the file aiomailru-0.0.3-py3-none-any.whl.

File metadata

  • Download URL: aiomailru-0.0.3-py3-none-any.whl
  • Upload date:
  • Size: 17.1 kB
  • Tags: Python 3
  • Uploaded using 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

File hashes

Hashes for aiomailru-0.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 a99483656b415b6d7c6b78421698626f5a83ab2d860fbf5adbb88949e243baf3
MD5 dc987f5088d866c5a1ed74c56838579f
BLAKE2b-256 339f32ae609c56af09d5635ec71d94df798e32e667a7370c432846e64aee6ced

See more details on using hashes here.

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