This version introduces breaking changes. Please see the migration guide below on how to migrate from older versions.
Changes
- Drop support for Python 2
- Split `reports_api` module into `client`, `exceptions`, `schema` modules
- Rename `ReportsApiSession` to `Client` and change its constructor arguments
- Remove `Reports` prefix from exception names
- Return objects with well-defined fields instead of dicts
- Use proper enums for parameters instead of string values
- Add type annotations
- Add token authentication method
- Add asynchronous client
Migration
Python compatibility
Python 2 is no longer supported, please use Python 3.7+.
Authentication
For example, previous code creating API client instance:
python
from rtbhouse_sdk.reports_api import ReportsApiSession
api = ReportsApiSession(username="myuser", password="mypassword")
Now should look like this:
python
from rtbhouse_sdk.client import BasicAuth, Client
api = Client(auth=BasicAuth(username="myuser", password="mypassword"))
Additionally, it is now possible to authenticate with a token:
python
from rtbhouse_sdk.client import BasicTokenAuth, Client
api = Client(auth=BasicTokenAuth(token="mytoken"))
Clients
Now SDK offers both synchronous and asynchronous clients to work with. They have the same set of endpoints.
It is recommended to close the session using `close()` method. For convenience there is also a context manager that takes care of that.
Usage example with sync client:
python
from rtbhouse_sdk.client import BasicTokenAuth, Client
auth = BasicTokenAuth(token='mytoken')
using close
api = Client(auth=auth)
info = api.get_user_info()
api.close()
or using context manager
with Client(auth=auth) as api:
info = api.get_user_info()
Usage example with async client:
python
from rtbhouse_sdk.client import BasicTokenAuth, AsyncClient
auth = BasicTokenAuth(token='mytoken')
using close
api = AsyncClient(auth=auth)
info = await api.get_user_info()
await api.close()
or using context manager
async with AsyncClient(auth=auth) as api:
info = await api.get_user_info()
Result data
Each endpoint method returns data in form of [Pydantic model](https://pydantic-docs.helpmanual.io/usage/models/).
If you wish to access the data as a dict, you can call `dict()` method on the resulting object.
For example, previous code fetching user info:
python
info = api.get_user_info()
print(info['isClientUser'])
Now should look like:
python
recommended way
info = api.get_user_info()
print(info.is_client_user)
alternative way using dict with camelCase keys
(same as in the code for previous SDK version)
info = api.get_user_info().dict(by_alias=True)
print(info['isClientUser'])
alternative way using dict with snake_case keys
info = api.get_user_info().dict()
print(info['is_client_user'])
Query params
Instead of plain strings there are now enums which should be used for query filters.
Moreover, `date` objects should be used for `day_from` and `day_to` parameters.
For example, previous code fetching stats:
python
from rtbhouse_sdk.reports_api import ReportsApiSession
api = ReportsApiSession(username="myuser", password="mypassword")
results = api.get_rtb_stats(
adv_hash="myadvertiser",
day_from="2022-06-01",
day_to="2022-06-30",
group_by=["subcampaign", "userSegment"],
metrics=["clicksCount"]
)
for row in results:
print(row["subcampaign"] + " - " + row["userSegment"] + ": " + str(row["clicksCount"]))
Now should look like this:
python
from datetime import date
from rtbhouse_sdk.client import Client, BasicAuth
from rtbhouse_sdk.schema import StatsGroupBy, StatsMetric
api = Client(auth=BasicAuth(username="myuser", password="mypassword"))
results = api.get_rtb_stats(
adv_hash="myadvertiser",
day_from=date(2022, 6, 1),
day_to=date(2022, 6, 30),
group_by=[StatsGroupBy.SUBCAMPAIGN, StatsGroupBy.USER_SEGMENT],
metrics=[StatsMetric.CLICKS_COUNT]
)
for row in results:
print(row.subcampaign + " - " + row.user_segment + ": " + str(row.clicks_count))
api.close()
Other changes
- `get_rtb_conversions` is now a generator function (previously it returned list)