## Python SDK

## Instant insights from any Python app

This documentation provides guidance on how to integrate the June SDK with your Python application. June SDK is a powerful library for tracking user interactions and events, offering similar functionality to the underlying Segment SDK.

## Getting Started

## Installation

To install the June SDK in your Python project, use the PIP package manager:

```sh
pip install june-analytics-python
```

## Configuration

First, you'll need to import the SDK into your application. Next, instantiate the client using the write key you've received when you created your June account:

```python
from june import analytics

analytics.write_key = "YOUR_WRITE_KEY"
```

Now you can use the analytics instance to track events, identify users, and more.

## API Reference

## Client

## June Python SDK Client Configuration

The June Python SDK allows you to configure several settings according to your needs. The available configuration parameters are:

## Initialization Parameters

| Option | Type | Description | Required |
| --- | --- | --- | --- |
| write_key | String | The write key for your project, obtained from June analytics. | Yes |
| host | String | The hostname to which events should be sent. | No |
| debug | Boolean | If set to "True", enables debug-level logging. | No |
| max_queue_size | Integer | The maximum size of the event queue. If the queue becomes full, new events may be dropped. | No |
| send | Boolean | If set to "False", no events will be sent. | No |
| on_error | Function | A function to call when an error occurs during event sending. | No |
| gzip | Boolean | If set to "True", events will be gzip-compressed before sending. | No |
| max_retries | Integer | The maximum number of retries if a request fails. | No |
| sync_mode | Boolean | If set to "True", events are sent synchronously. Otherwise, they are sent asynchronously. | No |
| timeout | Integer | The timeout for HTTP requests. | No |

Here's an example of how to configure the client:

```python
from june import analytics

analytics.write_key = "YOUR_WRITE_KEY"

analytics.host = "YOUR_HOST"

analytics.debug = True

analytics.max_queue_size = 10000

analytics.send = True

analytics.on_error = lambda error, items: print(error, items)

analytics.gzip = True

analytics.max_retries = 5

analytics.sync_mode = False

analytics.timeout = 10
```

## Tracking Events

To track events, you can use the `track` method:

```python
analytics.track(
  user_id="USER_ID",
  event="Signed In",
  properties={"browser": "chrome"},
)
```

Parameters:

| Parameter | Type | Description | Required |
| --- | --- | --- | --- |
| userId | String | The ID for this user in your database. Note: At least one of "userId" or "anonymousId" must be included in any track call. | No |
| anonymousId | String | An ID associated with the user when you don’t know who they are. Note: You must include at least one of "userId" or "anonymousId" in all track calls. | No |
| event | String | The name of the event you’re tracking. It is recommended to use human-readable names like "Song Played" or "Status Updated". | Yes |
| properties | Dictionary | A dictionary of properties for the event. For instance, if the event was "Product Added", it might have properties like price or product. | No |
| timestamp | DateTime | A DateTime object representing when the track took place. | No |
| context | Dictionary | A dictionary of extra context to attach to the call. | No |

## Identifying Users & Setting User Traits

To identify users, you can use the `identify` method:

```python
analytics.identify(
  user_id="USER_ID",
  traits={
    "email": "test@example.com",
    "name": "Joe Bloggs",
    "avatar": "https://avatar.com/0sd9fsd8y97a0sf99asd.png",
  },
)
```

Parameters:

| Parameter | Type | Description | Required |
| --- | --- | --- | --- |
| userId | String | The ID for this user in your database. Note: At least one of "userId" or "anonymousId" must be included in any identify call. | No |
| anonymousId | String | An ID associated with the user when you don’t know who they are. | No |
| traits | Dictionary | A dictionary of traits you know about the user. | No |
| timestamp | DateTime | A DateTime object representing when the identify took place. | No |
| context | Dictionary | A dictionary of extra context to attach to the call. | No |

## Grouping Users

To group users by organization or company, use the `group` method:

```python
analytics.group(
  user_id="USER_ID",
  group_id="GROUP_ID",
  traits={
    "name": "Acme Inc",
    "avatar": "https://avatar.com/0sd9fsd8y97a0sf99asd.png",
  },
)
```

Parameters:

| Parameter | Type | Description | Required |
| --- | --- | --- | --- |
| userId | String | The ID for this user in your database. | No |
| anonymousId | String | An ID associated with the user when you don’t know who they are. | No |
| groupId | String | The ID of the group. | Yes |
| traits | Dictionary | A dictionary of traits you know about the group. | No |
| timestamp | DateTime | A DateTime object representing when the group took place. | No |
| context | Dictionary | A dictionary of extra context to attach to the call. | No |

## Serverless environments

In serverless environments like AWS Lambda, your environment may finish the code execution before June SDK is able to send events to June API.

You can use the `flush` method to send all queued events to June or you can configure the SDK to flush events automatically.

## Flush events manually

```python
analytics.flush()
```

## Flush events automatically

If you set `sync_mode` to `True`, the SDK will flush events automatically after every event.

```python
analytics.sync_mode = True
```