> For the complete documentation index, see [llms.txt](https://docs.gofigr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gofigr.io/integrations/python.md).

# Python

GoFigr's Python package provides seamless figure capture for all major visualization libraries.

## Supported Libraries

| Library    | Auto-capture | Manual capture |
| ---------- | ------------ | -------------- |
| Matplotlib | ✅            | ✅              |
| Seaborn    | ✅            | ✅              |
| Plotly     | ✅            | ✅              |

## Jupyter Notebooks

### Auto-Configured Setup (Simplest)

Just load the extension:

```python
%load_ext gofigr
```

That's it! GoFigr will:

* Automatically use your default workspace from `gfconfig`
* Create or use an analysis named after your notebook
* Enable auto-publish (automatically captures all figures)

All figures you create will be automatically published:

```python
%load_ext gofigr

import matplotlib.pyplot as plt
import pandas as pd
import numpy as np

# Create a simple plot
df = pd.DataFrame({'x': np.random.randn(100), 'y': np.random.randn(100)})
plt.scatter(df['x'], df['y'])
plt.title('Random Scatter Plot')

# This figure is automatically published!
```

### Custom Configuration

For more control, use the `configure()` function:

```python
%load_ext gofigr

from gofigr.jupyter import configure, FindByName, ApiId, NotebookName

configure(
    workspace=FindByName("Primary Workspace", create=False),
    analysis=FindByName("My Analysis", create=True),
    auto_publish=True,
    default_metadata={
        'requested_by': "Alyssa",
        'study': 'Pivotal Trial 1'
    }
)
```

#### Configuration Options

| Option             | Description                                                             |
| ------------------ | ----------------------------------------------------------------------- |
| `workspace`        | `FindByName("Name")`, `ApiId("uuid")`, or `None` (use default)          |
| `analysis`         | `FindByName("Name", create=True)`, `NotebookName()`, or `ApiId("uuid")` |
| `auto_publish`     | If `True`, all figures are automatically published                      |
| `default_metadata` | Dictionary of metadata to store with each revision                      |
| `api_key`          | Override API key (if not using default from `gfconfig`)                 |

### Manual Publishing

If you set `auto_publish=False`, manually publish figures:

```python
%load_ext gofigr

from gofigr.jupyter import configure, FindByName, publish

configure(auto_publish=False, analysis=FindByName("My Analysis", create=True))

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
plt.title('Manual Publish Example')

# Manually publish
publish(fig=plt.gcf(), target=FindByName("My Figure", create=True))
```

***

## Standalone Scripts

Use the `Publisher` class for scripts outside Jupyter:

```python
import matplotlib.pyplot as plt
from gofigr.publisher import Publisher

# Initialize the publisher
pub = Publisher(workspace="My Workspace", analysis="Script Analysis")

# Create a figure
plt.plot([1, 2, 3], [1, 4, 9])
plt.title('Quadratic Function')

# Publish the figure
pub.publish(plt.gcf())
```

### Complete Script Example

```python
import seaborn as sns
import matplotlib.pyplot as plt
import plotly.express as px
from gofigr.publisher import Publisher

# Setup GoFigr Publisher
pub = Publisher(workspace="My Workspace", analysis="Penguin Analysis")

# Load data
penguins = sns.load_dataset("penguins")

# Create and publish a Seaborn plot
sns.scatterplot(data=penguins, x="flipper_length_mm", y="bill_length_mm", hue="species")
plt.title("Penguin Measurements (Seaborn)")
pub.publish(plt.gcf())

# Create and publish a Plotly plot
fig = px.scatter(penguins, x="flipper_length_mm", y="bill_length_mm", 
                 color="species", title="Penguin Measurements (Plotly)")
pub.publish(fig)
```

***

## Asset Tracking

GoFigr can automatically track data files used in your analyses.

### Using Tracked Data Reading

Use `gf.read_csv()` instead of `pd.read_csv()` to automatically track data:

```python
%load_ext gofigr

# gf is automatically available after loading the extension
df = gf.read_csv('data/penguins.csv')

# The DataFrame is now linked to the tracked asset
print(df.attrs.get('_gofigr_revision'))  # Shows the asset revision ID
```

### Supported Reading Methods

| Method              | File Type     |
| ------------------- | ------------- |
| `gf.read_csv()`     | CSV files     |
| `gf.read_excel()`   | Excel files   |
| `gf.read_json()`    | JSON files    |
| `gf.read_parquet()` | Parquet files |
| `gf.read_feather()` | Feather files |
| `gf.read_pickle()`  | Pickle files  |

All methods accept the same parameters as their pandas counterparts.

### Manual Asset Syncing

```python
# Sync a file without reading it
gf.sync.sync('data/penguins.csv')

# Or use as a context manager
with gf.sync.open('data/raw_data.txt', 'r') as f:
    content = f.read()
```