data-scientists/ocean.py/technical-details.md
---
description: Technical details about most used ocean.py functions
---
# Ocean Instance Tech Details
At the beginning of most flows, we create an `ocean` object, which is an instance of class [`Ocean`](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py). It exposes useful information, including the following:
* properties for config & OCEAN
* contract objects retrieval
* users' orders
* provider fees
### Constructor
* **\_\_init\_\_**(`self`, `config_dict: Dict`, `data_provider: Optional[Type] = None`)
The Ocean class is the entry point into Ocean Procol.
In order to initialize a Ocean object, you must provide `config_dict` which is a `Dictionary` instance and optionally a `DataServiceProvider` instance.
**Parameters**
* `config_dict`: `dict` which is mandatory and it contains the configuration as dictionary format.
* `data_provider`: `Optional[DataProvider]` which is optional with a default value of None. If it is not provided, the constructor will instantiate a new one from scratch.
**Returns**
`None`
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#L43)
<details>
<summary>Source code</summary>
{% code overflow="wrap" %}
```python
class Ocean:
"""The Ocean class is the entry point into Ocean Protocol."""
@enforce_types
def __init__(self, config_dict: Dict, data_provider: Optional[Type] = None) -> None:
"""Initialize Ocean class.
Usage: Make a new Ocean instance
`ocean = Ocean({...})`
This class provides the main top-level functions in ocean protocol:
1. Publish assets metadata and associated services
- Each asset is assigned a unique DID and a DID Document (DDO)
- The DDO contains the asset's services including the metadata
- The DID is registered on-chain with a URL of the metadata store
to retrieve the DDO from
`ddo = ocean.assets.create(metadata, publisher_wallet)`
2. Discover/Search ddos via the current configured metadata store (Aquarius)
- Usage:
`ddos_list = ocean.assets.search('search text')`
An instance of Ocean is parameterized by a `Config` instance.
:param config_dict: variable definitions
:param data_provider: `DataServiceProvider` instance
"""
config_errors = {}
for key, value in config_defaults.items():
if key not in config_dict:
config_errors[key] = "required"
continue
if not isinstance(config_dict[key], type(value)):
config_errors[key] = f"must be {type(value).__name__}"
if config_errors:
raise Exception(json.dumps(config_errors))
self.config_dict = config_dict
network_name = config_dict["NETWORK_NAME"]
check_network(network_name)
if not data_provider:
data_provider = DataServiceProvider
self.assets = OceanAssets(self.config_dict, data_provider)
self.compute = OceanCompute(self.config_dict, data_provider)
logger.debug("Ocean instance initialized: ")
```
{% endcode %}
</details>
### Config Getter
* **config**(`self`) -> `dict`
It is a helper method for retrieving the user's configuration for ocean.py.\
It can be called only by Ocean object and returns a python dictionary.
**Returns**
`dict`
Configuration fields as dictionary.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL265C1-L268C32)
<details>
<summary>Source code</summary>
```python
@property
@enforce_types
def config(self) -> dict: # alias for config_dict
return self.config_dict
```
</details>
### OCEAN Address
* **ocean_address**(`self`) -> `str`
It is a helper method for retrieving the OCEAN's token address.\
It can be called only by Ocean object and returns the address as a `string`.
**Returns**
`str`
OCEAN address for that network.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL100C1-L103C52)
<details>
<summary>Source code</summary>
```python
@property
@enforce_types
def OCEAN_address(self) -> str:
return get_ocean_token_address(self.config)
```
[`get_ocean_token_address`](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/util.py#LL31C1-L38C89) function is an utilitary function which gets the address from `address.json` file
{% code overflow="wrap" %}
```python
@enforce_types
def get_ocean_token_address(config_dict: dict) -> str:
"""Returns the OCEAN address for given network or web3 instance
Requires either network name or web3 instance.
"""
addresses = get_contracts_addresses(config_dict)
return Web3.toChecksumAddress(addresses.get("Ocean").lower()) if addresses else None
```
{% endcode %}
</details>
### OCEAN Token Object
* **ocean_token**(`self`) -> `DatatokenBase`
* **OCEAN**(`self`) -> `DatatokenBase` as alias for the above option
It is a helper method for retrieving the OCEAN token object (Datatoken class).\
It can be called within Ocean class and returns the OCEAN Datatoken.
**Returns**
`DatatokenBase`
OCEAN token as `DatatokenBase` object.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL105C1-L113C32)
<details>
<summary>Source code</summary>
```python
@property
@enforce_types
def OCEAN_token(self) -> DatatokenBase:
return DatatokenBase.get_typed(self.config, self.OCEAN_address)
@property
@enforce_types
def OCEAN(self): # alias for OCEAN_token
return self.OCEAN_token
```
</details>
### Data NFT Factory
* **data\_nft\_factory**(`self`) -> `DataNFTFactoryContract`
It is a property for getting `Data NFT Factory` object for the singleton smart contract.\
It can be called within Ocean class and returns the `DataNFTFactoryContract` instance.
**Returns**
`DataNFTFactoryContract`
Data NFT Factory contract object which access all the functionalities available from smart contracts in Python.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL117C1-L120C80)
<details>
<summary>Source code</summary>
{% code overflow="wrap" %}
```python
@property
@enforce_types
def data_nft_factory(self) -> DataNFTFactoryContract:
return DataNFTFactoryContract(self.config, self._addr("ERC721Factory"))
```
{% endcode %}
</details>
### Dispenser
* **dispenser**(`self`) -> `Dispenser`
`Dispenser` is represented by a faucet for free data.\
It is a property for getting `Dispenser` object for the singleton smart contract.\
It can be called within Ocean class and returns the `Dispenser` instance.
**Returns**
`Dispenser`
Dispenser contract object which access all the functionalities available from smart contracts in Python.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL122C1-L125C63)
<details>
<summary>Source code</summary>
```python
@property
@enforce_types
def dispenser(self) -> Dispenser:
return Dispenser(self.config, self._addr("Dispenser"))
```
</details>
### Fixed Rate Exchange
* **fixed\_rate\_exchange**(`self`) -> `FixedRateExchange`
Exchange is used for priced data.\
It is a property for getting `FixedRateExchange` object for the singleton smart contract.\
It can be called within Ocean class and returns the `FixedRateExchange` instance.
**Returns**
`FixedRateExchange`
Fixed Rate Exchange contract object which access all the functionalities available from smart contracts in Python.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL127C1-L130C72)
<details>
<summary>Source code</summary>
```python
@property
@enforce_types
def fixed_rate_exchange(self) -> FixedRateExchange:
return FixedRateExchange(self.config, self._addr("FixedPrice"))
```
</details>
### NFT Token Getter
* **get\_nft\_token**(`self`, `token_adress: str`) -> `DataNFT`
It is a getter for a specific data NFT object based on its checksumed address.\
It can be called within Ocean class which returns the `DataNFT` instance based on string `token_address` specified as parameter.
**Parameters**
* `token_address` - string checksumed address of the NFT token that you are searching for.
**Returns**
`DataNFT`
Data NFT object which access all the functionalities available for ERC721 template in Python.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL139C5-L145C51)
<details>
<summary>Source code</summary>
```python
@enforce_types
def get_nft_token(self, token_address: str) -> DataNFT:
"""
:param token_address: Token contract address, str
:return: `DataNFT` instance
"""
return DataNFT(self.config, token_address)
```
</details>
### Datatoken Getter
* **get\_datatoken**(`self`, `token_address: str`) -> `DatatokenBase`
It is a getter for a specific `datatoken` object based on its checksumed address.\
It can be called within Ocean class with a string `token_address` as parameter which returns the `DatatokenBase` instance depending on datatoken's template index.
**Parameters**
* `token_address` - string checksumed address of the datatoken that you are searching for.
**Returns**
`DatatokenBase`
Datatoken object which access all the functionalities available for ERC20 templates in Python.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL147C5-L153C67)
<details>
<summary>Source code</summary>
```python
@enforce_types
def get_datatoken(self, token_address: str) -> DatatokenBase:
"""
:param token_address: Token contract address, str
:return: `Datatoken1` or `Datatoken2` instance
"""
return DatatokenBase.get_typed(self.config, token_address)
```
</details>
### User Orders Getter
* **get\_user\_orders**(`self`, `address: str`, `datatoken: str`) -> `List[AttributeDict]`
Returns the list of orders that were made by a certain user on a specific datatoken.
It can be called within Ocean class.
**Parameters**
* `address` - wallet address of that user
* `datatoken` - datatoken address
**Returns**
`List[AttributeDict]`
List of all the orders on that `datatoken` done by the specified `user`.
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL157C5-L173C23)
<details>
<summary>Source code</summary>
{% code overflow="wrap" %}
```python
@enforce_types
def get_user_orders(self, address: str, datatoken: str) -> List[AttributeDict]:
"""
:return: List of orders `[Order]`
"""
dt = DatatokenBase.get_typed(self.config_dict, datatoken)
_orders = []
for log in dt.get_start_order_logs(address):
a = dict(log.args.items())
a["amount"] = int(log.args.amount)
a["address"] = log.address
a["transactionHash"] = log.transactionHash
a = AttributeDict(a.items())
_orders.append(a)
return _orders
```
{% endcode %}
</details>
### Provider Fees
* **retrieve\_provider\_fees**( `self`, `ddo: DDO`, `access_service: Service`, `publisher_wallet` ) -> `dict`
Calls Provider to compute provider fees as dictionary for access service.
**Parameters**
* `ddo` - the data asset which has the DDO object
* `access_service` - Service instance for the service that needs the provider fees
* `publisher_wallet` - Wallet instance of the user that wants to retrieve the provider fees
**Returns**
`dict`
A dictionary which contains the following keys (`providerFeeAddress`, `providerFeeToken`, `providerFeeAmount`, `providerData`, `v`, `r`, `s`, `validUntil`).
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL177C4-L189C1)
<details>
<summary>Source code</summary>
{% code overflow="wrap" %}
```python
@enforce_types
def retrieve_provider_fees(
self, ddo: DDO, access_service: Service, publisher_wallet
) -> dict:
initialize_response = DataServiceProvider.initialize(
ddo.did, access_service, consumer_address=publisher_wallet.address
)
initialize_data = initialize_response.json()
provider_fees = initialize_data["providerFee"]
return provider_fees
```
{% endcode %}
</details>
### Compute Provider Fees
* **retrieve\_provider\_fees\_for\_compute**(`self`, `datasets: List[ComputeInput]`, `algorithm_data: Union[ComputeInput, AlgorithmMetadata]`, `consumer_address: str`, `compute_environment: str`, `valid_until: int`) -> `dict`
Calls Provider to generate provider fees as dictionary for compute service.
**Parameters**
* `datasets` - list of `ComputeInput` which contains the data assets
* `algorithm_data` - necessary data for algorithm and it can be either a `ComputeInput` object, either just the algorithm metadata, `AlgorithmMetadata`
* `consumer_address` - address of the compute consumer wallet which is requesting the provider fees
* `compute_environment` - id provided from the compute environment as `string`
* `valid_until` - timestamp in UNIX miliseconds for the duration of provider fees for the compute service.
**Returns**
`dict`
A dictionary which contains the following keys (`providerFeeAddress`, `providerFeeToken`, `providerFeeAmount`, `providerData`, `v`, `r`, `s`, `validUntil`).
**Defined in**
[ocean/ocean.py](https://github.com/oceanprotocol/ocean.py/blob/main/ocean_lib/ocean/ocean.py#LL190C4-L210C1)
<details>
<summary>Source code</summary>
{% code overflow="wrap" %}
```python
@enforce_types
def retrieve_provider_fees_for_compute(
self,
datasets: List[ComputeInput],
algorithm_data: Union[ComputeInput, AlgorithmMetadata],
consumer_address: str,
compute_environment: str,
valid_until: int,
) -> dict:
initialize_compute_response = DataServiceProvider.initialize_compute(
[x.as_dictionary() for x in datasets],
algorithm_data.as_dictionary(),
datasets[0].service.service_endpoint,
consumer_address,
compute_environment,
valid_until,
)
return initialize_compute_response.json()
```
{% endcode %}
</details>