# Migrating from v4.x to v5.x

This document aims to assist you in migrating from analytix v4.2 to v5.0.
It does not aim to be entirely comprehensive, but instead cover the biggest changes to users.
All changed classes and methods have change descriptions in their docstrings.

!!! important
    Only changes between v4.2.3 and v5.0.0 are detailed here.
    For additional changes, view the [changelog](https://github.com/parafoxia/analytix/releases).

## Python support

* Support for Python 3.7 has been removed
* Support for Pythons 3.12 and 3.13-dev has been added

## Clients and shards

### Interfaces

A number of significant changes have been made to the client interfaces.

* There are now only two clients: `BaseClient` and `Client`
* These clients are both fully synchronous
    * An extension library may be made at some point for those that still need async capabilites
    * You should be able to run analytix in an executor if you absolutely need async support
* Clients no longer need to be torn down, but retain the context manager for the sake of ease
* Monetary data is now no longer accessible by default and the fetching of such data needs to be manually enabled
* Various method names have changed
* Sensitive data is no longer emitted in debug logs

### Authorisation

The clients are now much smarter and have much more power when it comes to authorisation.

* The scripting client is now able to detect if the stored token's scopes are sufficient to perform the requested action, and trigger reauthorisation if not
* This is done using the `scopes_are_sufficient` method of the clients, which is publically accessible
* Client, not shards, now handle token refreshing
* Shards can now be given a different set of scopes to their parent clients
* The scripting client's authorise method can no longer accept token file filenames -- the base client should be properly utilised in these instances
* You now have more control over when authorisation should be forced and when access tokens should be refreshed

### Reports

Report interfaces are very similar to before, but a few changes have been made.

* `AnalyticsReport` is now `Report`
* Files will no longer be overwritten by default
* You can now pass additional arguments to the `to_feather` and `to_parquet` methods to be passed to PyArrow's respective methods
* These methods also no longer return Arrow tables
* JSON exports are no longer indented by default
* You can also now pass additional arguments to `to_json` to be passed to `json.dump`
    * Because of this, `indent` is no longer an argument for this method
* The `Report` and `ResultTable` classes are now in separate files
    * The `ResultTable` class has not changed

### Groups

* `GroupList` and `GroupItemList` objects are now iterable
* You can now fetch a groups items by calling its `fetch_items` method
* Group objects are now documented!
