Update the Python API client

You should keep your Python API client up to date to benefit from improvements and bug fixes. Algolia’s Service Level Agreement only applies to the latest version of the API client.

The Python API client follows Semantic Versioning. You can check what the latest version of the API client is on the GitHub release page.

Upgrade to version 3.0.0

From version 2.x.x

This document lists every known breaking change:

• Remove support for Python 2
• Add support for Python 3.9 and above
• Remove deprecated RecommendationClient, use the PersonalizationClient instead

Update your algoliasearch dependency to >=3.0,<4.0 using pip:

$
python -m pip install --upgrade 'algoliasearch>=3.0,<4.0'

Then, update your requirements in your setup.py or requirements.txt to: algoliasearch>=3.0,<4.0.

From version 1.x.x

Follow the Upgrade from 1.20.0 to 2.0.0 and From versions 2.x.x guides.

Upgrade from 1.20.0 to 2.0.0

This document lists every known breaking change. Not all these changes may affect your application, since some of these breaking changes happen in obscure parts of the client.

Update your algoliasearch dependency to >=2.0,<3.0 using pip:

$
python -m pip install --upgrade 'algoliasearch>=2.0,<3.0'

Then, update your requirements in your setup.py or requirements.txt to: algoliasearch>=2.0,<3.0.

SearchClient

You can initialize the SearchClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- client = Client('app_id', 'api_key')

+ from algoliasearch.search_client import SearchClient
+ client = SearchClient.create('app_id', 'api_key')

List of method signature changes

SearchIndex

You can initialize the SearchIndex as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- index = Client('app_id', 'api_key').init_index('name')

+ from algoliasearch.search_client import SearchClient
+ index = SearchClient.create('app_id', 'api_key').init_index('name')

List of method signature changes

AnalyticsClient

You can initialize the AnalyticsClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- analytics = Client('app_id', 'api_key').init_analytics()

+ from algoliasearch.analytics_client import AnalyticsClient
+ analytics = AnalyticsClient.create('app_id', 'api_key')

List of method signature changes

InsightsClient

You can initialize the InsightsClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- insights = Client('app_id', 'api_key').init_insights()

+ from algoliasearch.insights_client import InsightsClient
+ insights = InsightsClient.create('app_id', 'api_key')

List of method signature changes

Using configuration

You can instantiate all clients with configuration objects. This is useful to change the way a client behaves.

All setters have been removed. If, for instance, you relied on set_extra_headers or set_timeout, you need to change your code to use a configuration object:

1
2
3
4
5
6
7
8
9
10
11
12
# v1
client.timeout = (1, 30)

# v2
from algoliasearch.configs import SearchConfig

config = SearchConfig()
config.read_timeout = 1
config.write_timeout = 30

client = SearchClient.create_with_config(config)

Optional methods parameters and requestOptions

To have the most consistent, predictable, and future-proof method signature, the API client follows three rules:

• All required parameters have a single argument each
• All optional arguments are passed in a request_options dict, as the last argument
• The client never sets any default values

Here are some examples:

1
2
3
4
5
# v1
client.get_logs(0, 100, 'all')

# v2
client.get_logs({'offset': 0, 'length': 100, 'type': 'all'})

1
2
3
4
5
6
7
8
9
10
11
12
forward_to_replicas = True
synonym = {
  'objectID': 'a-unique-identifier',
  'type': 'altCorrection1',
  # ...
}

# v1
index.save_synonym(synonym, 'a-unique-identifier', forward_to_replicas)

# v2
index.save_synonym(synonym, {'forwardToReplicas': forward_to_replicas})

1
2
3
4
5
6
7
object = {'foo': 'bar'}

# v1
index.add_object(object)

# v2
index.save_object(object, {'autoGenerateObjectIDIfNotExist': True})

1
2
3
4
5
6
7
settings = {"searchableAttributes": ["name", "address"]}

# v1
index.set_settings(settings, True)

# v2
index.set_settings(settings, {'forwardToReplicas': True})

Exceptions

The import of the base AlgoliaException exception has changed:

1
2
3
4
5
# v1
from algoliasearch.helpers import AlgoliaException

# v2
from algoliasearch.exceptions import AlgoliaException