Skip to content

Package Documentation

Vessel Consumptions API Package.

Classes:

Name Description
VesselConsumptionsAPI

Represents Signal's Vessel Consumptions API.
VesselConsumptions

Represents vessel consumptions data.
AdvertisedConsumptions

Represents advertised consumptions data.
AdvertisedConsumptionsPage

Represents a page of advertised consumptions.

AdvertisedConsumptions dataclass

Contains advertised consumptions data for a vessel.

Attributes:

Name Type Description
imo int

Vessel IMO
updated_date str

Date of last update
ballast_consumptions Optional[List[AdvertisedConsumptionAtSea]]

List of advertised ballast consumptions at sea
laden_consumptions Optional[List[AdvertisedConsumptionAtSea]]

List of advertised laden consumptions at sea
idle_consumptions Optional[List[AdvertisedConsumptionInPort]]

List of advertised idle consumptions in port
working_consumptions Optional[List[AdvertisedConsumptionInPort]]

List of advertised working consumptions in port
Source code in signal_ocean/vessel_consumptions/models.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
@dataclass(frozen=True)
class AdvertisedConsumptions:
    """Contains advertised consumptions data for a vessel.

    Attributes:
        imo: Vessel IMO
        updated_date: Date of last update
        ballast_consumptions: List of advertised ballast consumptions at sea
        laden_consumptions: List of advertised laden consumptions at sea
        idle_consumptions: List of advertised idle consumptions in port
        working_consumptions: List of advertised working consumptions in port

    """
    imo: int
    updated_date: str
    ballast_consumptions: Optional[List[AdvertisedConsumptionAtSea]] = None
    laden_consumptions: Optional[List[AdvertisedConsumptionAtSea]] = None
    idle_consumptions: Optional[List[AdvertisedConsumptionInPort]] = None
    working_consumptions: Optional[List[AdvertisedConsumptionInPort]] = None

    def __repr__(self) -> str:
        """Override of the default __repr__ function.

        Returns:
            Object string representation omitting None attributes

        """
        nodef_f_vals = (
            (f.name, attrgetter(f.name)(self))
            for f in dataclasses.fields(self)
            if attrgetter(f.name)(self) != f.default
        )

        nodef_f_repr = ", ".join(f"{name}={value}"
                                 for name, value
                                 in nodef_f_vals)
        return f"{self.__class__.__name__}({nodef_f_repr})"

    def to_dict(self) -> Dict[Any, Any]:
        """Cast AdvertisedConsumptions object to dict.

        Returns:
            Dict representation of AdvertisedConsumptions model

        """
        return dataclasses.asdict(
            self,
            dict_factory=lambda x: {
                _to_camel_case(k): v
                for (k, v) in x if v is not None
            })

__repr__()

Override of the default repr function.

Returns:

Type Description
str

Object string representation omitting None attributes
Source code in signal_ocean/vessel_consumptions/models.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def __repr__(self) -> str:
    """Override of the default __repr__ function.

    Returns:
        Object string representation omitting None attributes

    """
    nodef_f_vals = (
        (f.name, attrgetter(f.name)(self))
        for f in dataclasses.fields(self)
        if attrgetter(f.name)(self) != f.default
    )

    nodef_f_repr = ", ".join(f"{name}={value}"
                             for name, value
                             in nodef_f_vals)
    return f"{self.__class__.__name__}({nodef_f_repr})"

to_dict()

Cast AdvertisedConsumptions object to dict.

Returns:

Type Description
Dict[Any, Any]

Dict representation of AdvertisedConsumptions model
Source code in signal_ocean/vessel_consumptions/models.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
def to_dict(self) -> Dict[Any, Any]:
    """Cast AdvertisedConsumptions object to dict.

    Returns:
        Dict representation of AdvertisedConsumptions model

    """
    return dataclasses.asdict(
        self,
        dict_factory=lambda x: {
            _to_camel_case(k): v
            for (k, v) in x if v is not None
        })

AdvertisedConsumptionsPage dataclass

Contains a page of advertised consumptions.

Attributes:

Name Type Description
next_page_token Optional[str]

The key to retrieve the next page
data List[AdvertisedConsumptions]

List of advertised consumptions
Source code in signal_ocean/vessel_consumptions/models.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
@dataclass(frozen=True)
class AdvertisedConsumptionsPage:
    """Contains a page of advertised consumptions.

    Attributes:
        next_page_token: The key to retrieve the next page
        data: List of advertised consumptions

    """
    next_page_token: Optional[str] = None
    data: List[AdvertisedConsumptions] = dataclasses.field(
        default_factory=list
    )

    def to_dict(self) -> Dict[Any, Any]:
        """Cast AdvertisedConsumptionsPage object to dict.

        Returns:
            Dict representation of AdvertisedConsumptionsPage object

        """
        return {
            "NextPageToken": self.next_page_token,
            "Data": [
                advertised_consumptions.to_dict()
                for advertised_consumptions in self.data
            ]
        }

to_dict()

Cast AdvertisedConsumptionsPage object to dict.

Returns:

Type Description
Dict[Any, Any]

Dict representation of AdvertisedConsumptionsPage object
Source code in signal_ocean/vessel_consumptions/models.py 
209
210
211
212
213
214
215
216
217
218
219
220
221
222
def to_dict(self) -> Dict[Any, Any]:
    """Cast AdvertisedConsumptionsPage object to dict.

    Returns:
        Dict representation of AdvertisedConsumptionsPage object

    """
    return {
        "NextPageToken": self.next_page_token,
        "Data": [
            advertised_consumptions.to_dict()
            for advertised_consumptions in self.data
        ]
    }

VesselConsumptions dataclass

Contains vessel consumptions data.

Attributes:

Name Type Description
imo int

Vessel IMO
idle_consumption Optional[float]

Idle consumption value
load_port_consumption Optional[float]

Load port consumption value
discharge_port_consumption Optional[float]

Discharge port consumption value
auxiliary_idle_consumption Optional[float]

Auxiliary idle consumption value
auxiliary_ballast_consumption Optional[float]

Auxiliary ballast consumption value
auxiliary_laden_consumption Optional[float]

Auxiliary laden consumption value
laden_consumptions Optional[List[Consumption]]

List of laden consumptions
ballast_consumptions Optional[List[Consumption]]

List of ballast consumptions
Source code in signal_ocean/vessel_consumptions/models.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@dataclass(frozen=True)
class VesselConsumptions:
    """Contains vessel consumptions data.

    Attributes:
        imo: Vessel IMO
        idle_consumption: Idle consumption value
        load_port_consumption: Load port consumption value
        discharge_port_consumption: Discharge port consumption value
        auxiliary_idle_consumption: Auxiliary idle consumption value
        auxiliary_ballast_consumption: Auxiliary ballast consumption value
        auxiliary_laden_consumption: Auxiliary laden consumption value
        laden_consumptions: List of laden consumptions
        ballast_consumptions: List of ballast consumptions

    """
    imo: int
    idle_consumption: Optional[float] = None
    load_port_consumption: Optional[float] = None
    discharge_port_consumption: Optional[float] = None
    auxiliary_idle_consumption: Optional[float] = None
    auxiliary_ballast_consumption: Optional[float] = None
    auxiliary_laden_consumption: Optional[float] = None
    laden_consumptions: Optional[List[Consumption]] = None
    ballast_consumptions: Optional[List[Consumption]] = None

    def __repr__(self) -> str:
        """Override of the default __repr__ function.

        Returns:
            Object string representation omitting None attributes

        """
        nodef_f_vals = (
            (f.name, attrgetter(f.name)(self))
            for f in dataclasses.fields(self)
            if attrgetter(f.name)(self) != f.default
        )

        nodef_f_repr = ", ".join(f"{name}={value}"
                                 for name, value
                                 in nodef_f_vals)
        return f"{self.__class__.__name__}({nodef_f_repr})"

    def to_dict(self) -> Dict[Any, Any]:
        """Cast VesselConsumptions object to dict.

        Returns:
            Dict representation of VesselConsumptions model

        """
        return dataclasses.asdict(
            self,
            dict_factory=lambda x: {
                _to_camel_case(k): v
                for (k, v) in x if v is not None
            })

__repr__()

Override of the default repr function.

Returns:

Type Description
str

Object string representation omitting None attributes
Source code in signal_ocean/vessel_consumptions/models.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def __repr__(self) -> str:
    """Override of the default __repr__ function.

    Returns:
        Object string representation omitting None attributes

    """
    nodef_f_vals = (
        (f.name, attrgetter(f.name)(self))
        for f in dataclasses.fields(self)
        if attrgetter(f.name)(self) != f.default
    )

    nodef_f_repr = ", ".join(f"{name}={value}"
                             for name, value
                             in nodef_f_vals)
    return f"{self.__class__.__name__}({nodef_f_repr})"

to_dict()

Cast VesselConsumptions object to dict.

Returns:

Type Description
Dict[Any, Any]

Dict representation of VesselConsumptions model
Source code in signal_ocean/vessel_consumptions/models.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
def to_dict(self) -> Dict[Any, Any]:
    """Cast VesselConsumptions object to dict.

    Returns:
        Dict representation of VesselConsumptions model

    """
    return dataclasses.asdict(
        self,
        dict_factory=lambda x: {
            _to_camel_case(k): v
            for (k, v) in x if v is not None
        })

VesselConsumptionsAPI

Represents Signal's Vessel Consumptions API.

Source code in signal_ocean/vessel_consumptions/vessel_consumptions_api.py 
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
class VesselConsumptionsAPI:
    """Represents Signal's Vessel Consumptions API."""

    relative_url = "vessel-consumptions-api/v1/"

    def __init__(self, connection: Optional[Connection] = None):
        """Initializes VesselConsumptionsAPI.

        Args:
            connection: API connection configuration. If not provided, the
                default connection method is used.
        """
        if connection is not None:
            vc_connection = copy.deepcopy(connection)
            func_type = type(
                vc_connection._Connection__get_headers  # type: ignore
            )
            vc_connection._Connection__get_headers = func_type(  # type: ignore
                custom_headers, vc_connection
            )
            self.__connection = vc_connection
        else:
            connection = Connection()
            func_type = type(
                connection._Connection__get_headers  # type: ignore
            )
            connection._Connection__get_headers = func_type(  # type: ignore
                custom_headers, connection
            )
            self.__connection = connection

    def __get_single(
            self,
            relative_url: str,
            cls: Type[TModel]
    ) -> Optional[TModel]:
        response = self.__connection._make_get_request(relative_url)

        if response.status_code in (
            requests.codes.not_found,
            requests.codes.no_content,
        ):
            return None

        response.raise_for_status()
        data = response.json()
        return parse_model(data, cls)

    def get_consumptions(
            self,
            imo: int
    ) -> Optional[VesselConsumptions]:
        """Retrieves vessel consumptions by IMO.

        Args:
            imo: Vessel IMO to retrieve consumptions for.

        Returns:
            VesselConsumptions or None if no vessel with
            the specified IMO has been found.
        """
        query_url = make_url('vessels', imo, 'consumptions')
        url = urljoin(VesselConsumptionsAPI.relative_url, query_url)
        return self.__get_single(url, VesselConsumptions)

    def get_advertised_consumptions(
            self,
            imo: int
    ) -> Optional[AdvertisedConsumptions]:
        """Retrieves advertised consumptions by IMO.

        Args:
            imo: Vessel IMO to retrieve advertised consumptions for.

        Returns:
            AdvertisedConsumptions or None if no vessel with
            the specified IMO has been found.
        """
        query_url = make_url('vessels', imo, 'advertisedConsumptions')
        url = urljoin(VesselConsumptionsAPI.relative_url, query_url)
        return self.__get_single(url, AdvertisedConsumptions)

    def get_advertised_consumptions_paginated(
            self,
            token: Optional[str] = None,
            page_size: Optional[int] = None
    ) -> Optional[AdvertisedConsumptionsPage]:
        """Retrieves a paginated list of all advertised consumptions.

        Args:
            token: Next page token for pagination.
            page_size: Number of results per page.

        Returns:
            AdvertisedConsumptionsPage containing advertised consumptions
            and a token for the next page.
        """
        params = {}
        if token is not None:
            params['token'] = token
        if page_size is not None:
            params['pageSize'] = str(page_size)
        query_url = make_url('vessels', 'advertisedConsumptions', **params)
        url = urljoin(VesselConsumptionsAPI.relative_url, query_url)
        return self.__get_single(url, AdvertisedConsumptionsPage)

__init__(connection=None)

Initializes VesselConsumptionsAPI.

Parameters:

Name Type Description Default
connection Optional[Connection]

API connection configuration. If not provided, the default connection method is used.

 None
Source code in signal_ocean/vessel_consumptions/vessel_consumptions_api.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def __init__(self, connection: Optional[Connection] = None):
    """Initializes VesselConsumptionsAPI.

    Args:
        connection: API connection configuration. If not provided, the
            default connection method is used.
    """
    if connection is not None:
        vc_connection = copy.deepcopy(connection)
        func_type = type(
            vc_connection._Connection__get_headers  # type: ignore
        )
        vc_connection._Connection__get_headers = func_type(  # type: ignore
            custom_headers, vc_connection
        )
        self.__connection = vc_connection
    else:
        connection = Connection()
        func_type = type(
            connection._Connection__get_headers  # type: ignore
        )
        connection._Connection__get_headers = func_type(  # type: ignore
            custom_headers, connection
        )
        self.__connection = connection

get_advertised_consumptions(imo)

Retrieves advertised consumptions by IMO.

Parameters:

Name Type Description Default
imo int

Vessel IMO to retrieve advertised consumptions for.

 required

Returns:

Type Description
Optional[AdvertisedConsumptions]

AdvertisedConsumptions or None if no vessel with
Optional[AdvertisedConsumptions]

the specified IMO has been found.
Source code in signal_ocean/vessel_consumptions/vessel_consumptions_api.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def get_advertised_consumptions(
        self,
        imo: int
) -> Optional[AdvertisedConsumptions]:
    """Retrieves advertised consumptions by IMO.

    Args:
        imo: Vessel IMO to retrieve advertised consumptions for.

    Returns:
        AdvertisedConsumptions or None if no vessel with
        the specified IMO has been found.
    """
    query_url = make_url('vessels', imo, 'advertisedConsumptions')
    url = urljoin(VesselConsumptionsAPI.relative_url, query_url)
    return self.__get_single(url, AdvertisedConsumptions)

get_advertised_consumptions_paginated(token=None, page_size=None)

Retrieves a paginated list of all advertised consumptions.

Parameters:

Name Type Description Default
token Optional[str]

Next page token for pagination.

 None
page_size Optional[int]

Number of results per page.

 None

Returns:

Type Description
Optional[AdvertisedConsumptionsPage]

AdvertisedConsumptionsPage containing advertised consumptions
Optional[AdvertisedConsumptionsPage]

and a token for the next page.
Source code in signal_ocean/vessel_consumptions/vessel_consumptions_api.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def get_advertised_consumptions_paginated(
        self,
        token: Optional[str] = None,
        page_size: Optional[int] = None
) -> Optional[AdvertisedConsumptionsPage]:
    """Retrieves a paginated list of all advertised consumptions.

    Args:
        token: Next page token for pagination.
        page_size: Number of results per page.

    Returns:
        AdvertisedConsumptionsPage containing advertised consumptions
        and a token for the next page.
    """
    params = {}
    if token is not None:
        params['token'] = token
    if page_size is not None:
        params['pageSize'] = str(page_size)
    query_url = make_url('vessels', 'advertisedConsumptions', **params)
    url = urljoin(VesselConsumptionsAPI.relative_url, query_url)
    return self.__get_single(url, AdvertisedConsumptionsPage)

get_consumptions(imo)

Retrieves vessel consumptions by IMO.

Parameters:

Name Type Description Default
imo int

Vessel IMO to retrieve consumptions for.

 required

Returns:

Type Description
Optional[VesselConsumptions]

VesselConsumptions or None if no vessel with
Optional[VesselConsumptions]

the specified IMO has been found.
Source code in signal_ocean/vessel_consumptions/vessel_consumptions_api.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def get_consumptions(
        self,
        imo: int
) -> Optional[VesselConsumptions]:
    """Retrieves vessel consumptions by IMO.

    Args:
        imo: Vessel IMO to retrieve consumptions for.

    Returns:
        VesselConsumptions or None if no vessel with
        the specified IMO has been found.
    """
    query_url = make_url('vessels', imo, 'consumptions')
    url = urljoin(VesselConsumptionsAPI.relative_url, query_url)
    return self.__get_single(url, VesselConsumptions)