Metadata-Version: 2.4
Name: port-ocean
Version: 0.61.7
Summary: Port Ocean is a Python framework for building integrations that ingest data into Port, the platform for building your AI software factory.
License-File: LICENSE.md
Keywords: ocean,port-ocean,port
Author: Daniel Sinai
Author-email: daniel@getport.io
Requires-Python: >=3.12,<4.0
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Provides-Extra: aws-vault
Provides-Extra: cli
Requires-Dist: aiofiles (>=25.1.0,<26.0.0)
Requires-Dist: aiostream (>=0.5.2,<0.7.0)
Requires-Dist: boto3 (>=1.43.106,<2.0.0) ; extra == "aws-vault"
Requires-Dist: certifi (>=2026.10.19)
Requires-Dist: click (>=8.5.0,<9.0.0) ; extra == "cli"
Requires-Dist: confluent-kafka (>=2.15.1,<3.0.0)
Requires-Dist: cookiecutter (>=2.1.1,<3.0.0) ; extra == "cli"
Requires-Dist: cryptography (>=50.0.2,<51.0.0)
Requires-Dist: fastapi (>=0.162.0,<0.163.0)
Requires-Dist: filelock (>=4.2.1,<5.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: ijson (>=3.4.0,<4.0.0)
Requires-Dist: jinja2 (>=3.1.6)
Requires-Dist: jinja2-strcase (>=0.0.2,<0.0.3) ; extra == "cli"
Requires-Dist: jinja2-time (>=0.2.0,<0.3.0) ; extra == "cli"
Requires-Dist: jmespath (>=1.0.1,<2.0.0)
Requires-Dist: jq (>=1.13.0,<2.0.0)
Requires-Dist: jsonref (>=1.1.0,<2.0.0) ; extra == "cli"
Requires-Dist: loguru (>=0.7.0,<0.8.0)
Requires-Dist: opentelemetry-api (>=1.45.1)
Requires-Dist: prometheus-client (>=0.26.0,<0.27.0)
Requires-Dist: psutil (>=7.2.1,<8.0.0)
Requires-Dist: pydantic-settings (>=2.13.0,<3.0.0)
Requires-Dist: pydantic[dotenv] (>=2.13.5,<3.0.0)
Requires-Dist: pydispatcher (>=2.0.7,<3.0.0)
Requires-Dist: pyhumps (>=3.8.0,<4.0.0)
Requires-Dist: pyjwt (>=2.15.1,<3.0.0)
Requires-Dist: pytest-cov (>=6,<8)
Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
Requires-Dist: python-dotenv (>=1.2.4,<2.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: redis[hiredis] (>=8.1.0,<9.0.0)
Requires-Dist: rich (>=13.4.1,<14.0.0) ; extra == "cli"
Requires-Dist: six (>=1.16.0,<2.0.0)
Requires-Dist: starlette (>=1.7.0,<2.0)
Requires-Dist: tomli (>=2.0.1,<3.0.0)
Requires-Dist: urllib3 (>=2.8.0,<3.0.0)
Requires-Dist: uvicorn (>=0.54.0,<0.55.0)
Requires-Dist: virtualenv (>=21.14.13,<22.0.0)
Requires-Dist: werkzeug (>=3.1.9,<4.0.0)
Project-URL: Documentation, https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/ocean-framework/overview/
Project-URL: Homepage, https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/ocean-framework/overview/
Project-URL: Repository, https://github.com/port-labs/ocean
Description-Content-Type: text/markdown

<img src="./assets/Thumbnail.png" alt="Ocean">

# Ocean <img src="./assets/OceanSymbol.svg" alt="Ocean" width="100" height="100" align="right">

[![Lint](https://github.com/port-labs/Port-Ocean/actions/workflows/lint.yml/badge.svg)](https://github.com/port-labs/port-ocean/actions/workflows/lint.yml)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/port-labs/ocean)

Ocean is Port's open source integration framework. It makes it easy to ingest data from your third-party tools and infrastructure into Port, the platform for building your AI software factory.

## Prerequisites

- Python 3.12

## Installation

In order to install the Ocean Framework, run the following command:

```bash
pip install "port-ocean[cli]"
```

Or

```bash
poetry add "port-ocean[cli]"
```

## Run Integration

1. source the integration venv

   ```bash
   . .venv/bin/activate
   ```

2. Run

   ```bash
   ocean sail ./path/to/integration
   ```

# Export Architecture

![image](./assets/ExportArchitecture.svg)

## Real-Time updates Architecture

![image](./assets/RealTimeUpdatesArchitecture.svg)

## Integration Lifecycle

![image](./assets/LifecycleOfIntegration.svg)

## Folder Structure

The Ocean Integration Framework follows a specific folder structure within this mono repository. This structure ensures proper organization and easy identification of integration modules. The suggested folder structure is as follows:

```
port-ocean/
├── port_ocean (framework)/
│ ├── ocean.py
│ ├── core/
| └── ...
└── integrations/
│  └─── integration_name/
│     ├──── main.py
│     ├──── pyproject.toml
│     └──── Dockerfile
├── ...
└── ...
```

- The `framework` folder contains the core logic for managing the integration lifecycle.
- Each integration is represented by a separate folder inside the `integrations` directory.
- Inside each integration folder, you'll find a `main.py` file that implements the core functionality of the integration for the specific third-party system.
- The `pyproject.toml` file inside each integration folder lists the required dependencies for that integration.

## Configuration

The Integration Framework utilizes a `config.yaml` file for its configuration. This file defines both the framework configuration and the integration configuration within it. Each integration is identified by its type and unique identifier, which are utilized during initialization to appropriately update Port.

Example `config.yaml`:

```yaml
# This is an example configuration file for the integration service.
# Please copy this file to config.yaml file in the integration folder and edit it to your needs.

port:
  clientId: PORT_CLIENT_ID # Can be loaded via environment variable: PORT_CLIENT_ID
  clientSecret: PORT_CLIENT_SECRET # Can be loaded via environment variable: PORT_CLIENT_SECRET
  baseUrl: https://api.getport.io/v1
# The event listener to use for the integration service.
eventListener:
  type: KAFKA / WEBHOOK
integration:
  # The name of the integration.
  identifier: "my_integration"
  # The type of the integration.
  type: "PagerDuty"
  config:
    my_git_token: "random"
    some_other_integration_config: "Very important information"
```

## Contributing

The reason Ocean is open source is that we aim for the Port integration library to offer numerous useful out-of-the-box integrations. We have confidence that developers and DevOps professionals who rely on Port in their everyday work will be inclined to contribute and assist in making it a comprehensive tool.

In order to learn how you can contribute to Ocean, read our [contributing guide](./CONTRIBUTING.md)

### Local Development (Framework)

1. Clone the repository

2. Install dependencies:

   ```bash
   make install
   ```

   Or (For installing integrations dependencies as well)

   ```bash
   make install/all
   ```

3. source the integration venv

   ```bash
   . .venv/bin/activate
   ```

### Local Development (Integration)

1. Clone the repository

2. For new integration run

   ```bash
   make new
   ```

   and follow the instructions

3. Install dependencies

4. ```bash
   cd DESIRED_INTEGRATION_FOLDER && make install
   ```

5. source the integration venv

   ```bash
   . .venv/bin/activate
   ```

6. Run the integration

   ```bash
   make run
   ```

   Or

   ```bash
   ocean sail
   ```

### Local Redis (live events and centralized rate limiter)

Live events (Redis streams) and the centralized rate limiter need Redis. For local runs, start one in Docker (logical DB 0 for live events, DB 1 for the rate limiter):

```bash
make redis/up && eval "$(make -s redis/env)"
```

Run `ocean sail` in the same shell. `make redis/env` only prints the `OCEAN__*` exports, so `eval` is what applies them to your shell.

| Command | Description |
| --- | --- |
| `make redis/up` | Start Redis on `localhost:6379` (idempotent) |
| `make redis/env` | Print the `OCEAN__LIVE_EVENTS__*` and `OCEAN__CENTRALIZED_RATE_LIMITER__*` exports |
| `make redis/status` | Container state, PING, and key count per DB |
| `make redis/down` | Stop and remove the container (data is not persisted) |
| `./scripts/local-redis.sh cli` | Open `redis-cli` in the container |

If port 6379 is already in use, pick another one and pass it to every command, e.g. `OCEAN_LOCAL_REDIS_PORT=6380 make redis/up`.

## License

The Ocean Framework is open-source software licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). See the [LICENSE](./LICENSE) file for more information.

## Contact

For any questions or inquiries, please reach out to our team at support@getport.io

