Skip to content

Package Documentation

Tonnage List API Package.

Area dataclass

A geographical area.

Attributes:

Name Type Description
id int

The area's id.
name str

The area's name.
location_taxonomy str

The area's location taxonomy. See the LocationTaxonomy class for available values.
taxonomy_id int

Location taxonomy id
Source code in signal_ocean/tonnage_list/models.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
@dataclass(frozen=True)
class Area:
    """A geographical area.

    Attributes:
        id: The area's id.
        name: The area's name.
        location_taxonomy: The area's location taxonomy. See the
            `LocationTaxonomy` class for available values.
        taxonomy_id: Location taxonomy id
    """

    id: int
    name: str
    location_taxonomy: str
    taxonomy_id: int

Column

Contains constants for data frame column names.

Source code in signal_ocean/tonnage_list/data_frame.py 
 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
 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
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
193
194
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
223
224
225
226
class Column(metaclass=IterableConstants):
    """Contains constants for data frame column names."""

    NAME = "name"
    """The vessel's name."""

    VESSEL_CLASS = _category("vessel_class")
    """Name of the vessel class the vessel is categorized as."""

    ICE_CLASS = _category("ice_class")
    """The vessel's ice class."""

    YEAR_BUILT = "year_built"
    """The year the vessel has been built."""

    DEADWEIGHT = "deadweight"
    """The vessel's deadweight."""

    LENGTH_OVERALL = "length_overall"
    """The vessel's length overall."""

    BREADTH_EXTREME = "breadth_extreme"
    """The vessel's breadth extreme."""

    SUBCLASS = _category("subclass")
    """The vessel's subclass. See the `VesselSubclass` class for available
    values."""

    MARKET_DEPLOYMENT = _category(_pit_col("market_deployment"))
    """Market deployment of the vessel at the tonnage lists' point in time. See
    the `MarketDeployment` class for available values."""

    PUSH_TYPE = _category(_pit_col("push_type"))
    """Push type of the vessel at the tonnage lists' point in time. See the
    `PushType` class for available values."""

    OPEN_PORT_ID = _category(_pit_col("open_port_id"))
    """The vessel's open port id at the tonnage lists' point in time."""

    OPEN_PORT = _category(_pit_col("open_port"))
    """The vessel's open port name at the tonnage lists' point in time."""

    OPEN_DATE = _pit_col("open_date")
    """The vessel's open date at the tonnage lists' point in time."""

    OPERATIONAL_STATUS = _category(_pit_col("operational_status"))
    """Operational status of the vessel at the tonnage lists' point in time.
    See the `OperationalStatus` class for available values."""

    COMMERCIAL_OPERATOR_ID = _category(_pit_col("commercial_operator_id"))
    """The vessel's commercial operator id at the tonnage lists' point in
    time."""

    COMMERCIAL_OPERATOR = _category(_pit_col("commercial_operator"))
    """The vessel's commercial operator at the tonnage lists' point in time."""

    COMMERCIAL_STATUS = _category(_pit_col("commercial_status"))
    """Commercial status of the vessel at the tonnage lists' point in time. See
    the `CommercialStatus` class for available values."""

    ETA = _pit_col("eta")
    """Estimated time of arrival at the tonnage lists' point in time."""

    LATEST_AIS = _pit_col("latest_ais")
    """Timestamp of the vessel's latest AIS information at the tonnage lists'
    point in time."""

    OPEN_PREDICTION_ACCURACY = _category(_pit_col("open_prediction_accuracy"))
    """How accurate, in terms of location taxonomy, is the vessel's open
    prediction at the tonnage lists' point in time. See the `LocationTaxonomy`
    class for available values."""

    OPEN_COUNTRY = _category(_pit_col("open_country"))
    """The country at which the vessel opens."""

    OPEN_NARROW_AREA = _category(_pit_col("open_narrow_area"))
    """The narrow geographical area at which the vessel opens."""

    OPEN_WIDE_AREA = _category(_pit_col("open_wide_area"))
    """The wide geographical area at which the vessel opens."""

    AVAILABILITY_PORT_TYPE = _category(_pit_col("availability_port_type"))
    """Prediction source of the vessel's open port at the tonnage lists' point
    in time. See the `SourceType` class for possible values."""

    AVAILABILITY_DATE_TYPE = _category(_pit_col("availability_date_type"))
    """Prediction source of the vessel's open date at the tonnage lists' point
    in time. See the `SourceType` class for possible values."""

    FIXTURE_TYPE = _category(_pit_col("fixture_type"))
    """Fixture type. One of Scraped, Manual, Implied"""

    CURRENT_VESSEL_SUB_TYPE_ID = _category(
                                    _pit_col("current_vessel_sub_type_id")
                                          )
    """Current vessel sub type Id"""

    CURRENT_VESSEL_SUB_TYPE = _category(_pit_col("current_vessel_sub_type"))
    """One of: -1: Unknown, 1: Dirty, 2: Clean"""

    WILLING_TO_SWITCH_CURRENT_VESSEL_SUB_TYPE = _pit_col(
                    "willing_to_switch_current_vessel_sub_type"
                                                         )
    """If the vessel is willing to compete on a different vessel subclass
    category or not"""

    @staticmethod
    def _create_row(
        name: str,
        vessel_class: str,
        ice_class: Optional[str],
        year_built: int,
        deadweight: int,
        length_overall: float,
        breadth_extreme: int,
        subclass: str,
        market_deployment: str,
        push_type: str,
        open_port_id: int,
        open_port: str,
        open_date: Optional[datetime],
        operational_status: str,
        commercial_operator_id: int,
        commercial_operator: str,
        commercial_status: str,
        eta: Optional[datetime],
        latest_ais: Optional[datetime],
        open_prediction_accuracy: str,
        open_country: Optional[str],
        open_narrow_area: Optional[str],
        open_wide_area: Optional[str],
        availability_port_type: str,
        availability_date_type: str,
        fixture_type: str,
        current_vessel_sub_type_id: int,
        current_vessel_sub_type: str,
        willing_to_switch_current_vessel_sub_type: bool,
    ) -> DataFrameRow:
        return (
            name,
            vessel_class,
            ice_class,
            year_built,
            deadweight,
            length_overall,
            breadth_extreme,
            subclass,
            market_deployment,
            push_type,
            open_port_id,
            open_port,
            open_date,
            operational_status,
            commercial_operator_id,
            commercial_operator,
            commercial_status,
            eta,
            latest_ais,
            open_prediction_accuracy,
            open_country,
            open_narrow_area,
            open_wide_area,
            availability_port_type,
            availability_date_type,
            fixture_type,
            current_vessel_sub_type_id,
            current_vessel_sub_type,
            willing_to_switch_current_vessel_sub_type
        )

    @staticmethod
    def _get_data_types() -> Dict[str, str]:
        return _data_types

AVAILABILITY_DATE_TYPE = _category(_pit_col('availability_date_type')) class-attribute instance-attribute

Prediction source of the vessel's open date at the tonnage lists' point in time. See the SourceType class for possible values.

AVAILABILITY_PORT_TYPE = _category(_pit_col('availability_port_type')) class-attribute instance-attribute

Prediction source of the vessel's open port at the tonnage lists' point in time. See the SourceType class for possible values.

BREADTH_EXTREME = 'breadth_extreme' class-attribute instance-attribute

The vessel's breadth extreme.

COMMERCIAL_OPERATOR = _category(_pit_col('commercial_operator')) class-attribute instance-attribute

The vessel's commercial operator at the tonnage lists' point in time.

COMMERCIAL_OPERATOR_ID = _category(_pit_col('commercial_operator_id')) class-attribute instance-attribute

The vessel's commercial operator id at the tonnage lists' point in time.

COMMERCIAL_STATUS = _category(_pit_col('commercial_status')) class-attribute instance-attribute

Commercial status of the vessel at the tonnage lists' point in time. See the CommercialStatus class for available values.

CURRENT_VESSEL_SUB_TYPE = _category(_pit_col('current_vessel_sub_type')) class-attribute instance-attribute

One of: -1: Unknown, 1: Dirty, 2: Clean

CURRENT_VESSEL_SUB_TYPE_ID = _category(_pit_col('current_vessel_sub_type_id')) class-attribute instance-attribute

Current vessel sub type Id

DEADWEIGHT = 'deadweight' class-attribute instance-attribute

The vessel's deadweight.

ETA = _pit_col('eta') class-attribute instance-attribute

Estimated time of arrival at the tonnage lists' point in time.

FIXTURE_TYPE = _category(_pit_col('fixture_type')) class-attribute instance-attribute

Fixture type. One of Scraped, Manual, Implied

ICE_CLASS = _category('ice_class') class-attribute instance-attribute

The vessel's ice class.

LATEST_AIS = _pit_col('latest_ais') class-attribute instance-attribute

Timestamp of the vessel's latest AIS information at the tonnage lists' point in time.

LENGTH_OVERALL = 'length_overall' class-attribute instance-attribute

The vessel's length overall.

MARKET_DEPLOYMENT = _category(_pit_col('market_deployment')) class-attribute instance-attribute

Market deployment of the vessel at the tonnage lists' point in time. See the MarketDeployment class for available values.

NAME = 'name' class-attribute instance-attribute

The vessel's name.

OPEN_COUNTRY = _category(_pit_col('open_country')) class-attribute instance-attribute

The country at which the vessel opens.

OPEN_DATE = _pit_col('open_date') class-attribute instance-attribute

The vessel's open date at the tonnage lists' point in time.

OPEN_NARROW_AREA = _category(_pit_col('open_narrow_area')) class-attribute instance-attribute

The narrow geographical area at which the vessel opens.

OPEN_PORT = _category(_pit_col('open_port')) class-attribute instance-attribute

The vessel's open port name at the tonnage lists' point in time.

OPEN_PORT_ID = _category(_pit_col('open_port_id')) class-attribute instance-attribute

The vessel's open port id at the tonnage lists' point in time.

OPEN_PREDICTION_ACCURACY = _category(_pit_col('open_prediction_accuracy')) class-attribute instance-attribute

How accurate, in terms of location taxonomy, is the vessel's open prediction at the tonnage lists' point in time. See the LocationTaxonomy class for available values.

OPEN_WIDE_AREA = _category(_pit_col('open_wide_area')) class-attribute instance-attribute

The wide geographical area at which the vessel opens.

OPERATIONAL_STATUS = _category(_pit_col('operational_status')) class-attribute instance-attribute

Operational status of the vessel at the tonnage lists' point in time. See the OperationalStatus class for available values.

PUSH_TYPE = _category(_pit_col('push_type')) class-attribute instance-attribute

Push type of the vessel at the tonnage lists' point in time. See the PushType class for available values.

SUBCLASS = _category('subclass') class-attribute instance-attribute

The vessel's subclass. See the VesselSubclass class for available values.

VESSEL_CLASS = _category('vessel_class') class-attribute instance-attribute

Name of the vessel class the vessel is categorized as.

WILLING_TO_SWITCH_CURRENT_VESSEL_SUB_TYPE = _pit_col('willing_to_switch_current_vessel_sub_type') class-attribute instance-attribute

If the vessel is willing to compete on a different vessel subclass category or not

YEAR_BUILT = 'year_built' class-attribute instance-attribute

The year the vessel has been built.

CommercialStatus

Contains constants for available commercial statuses.

Source code in signal_ocean/tonnage_list/models.py 
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
class CommercialStatus(metaclass=IterableConstants):
    """Contains constants for available commercial statuses."""

    ON_SUBS = "On Subs"
    """The vessel is "on subs" for a new fixture."""

    FAILED = "Failed"
    """The last fixture failed for this vessel."""

    CANCELLED = "Cancelled"
    """The last fixture has been cancelled for this vessel."""

    AVAILABLE = "Available"
    """The vessel is available for a new voyage after its open date."""

    POTENTIALLY_FIXED = "Poss Fixed"
    """The vessel is assumed to be fixed for a new voyage based on available
    AIS information.
    """

AVAILABLE = 'Available' class-attribute instance-attribute

The vessel is available for a new voyage after its open date.

CANCELLED = 'Cancelled' class-attribute instance-attribute

The last fixture has been cancelled for this vessel.

FAILED = 'Failed' class-attribute instance-attribute

The last fixture failed for this vessel.

ON_SUBS = 'On Subs' class-attribute instance-attribute

The vessel is "on subs" for a new fixture.

POTENTIALLY_FIXED = 'Poss Fixed' class-attribute instance-attribute

The vessel is assumed to be fixed for a new voyage based on available AIS information.

DateRange

A range of dates between a start and end date.

Source code in signal_ocean/tonnage_list/models.py 
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
class DateRange:
    """A range of dates between a start and end date."""

    def __init__(self, start: Optional[date], end: Optional[date]):
        """Creates the date range.

        Args:
            start: The start date of the range (inclusive).
            end: The end date of the range (inclusive).
        """
        if start is not None and end is not None and end < start:
            raise ValueError("Start date cannot be after end date.")

        self.start = start
        self.end = end

    def _split(self, max_days: int) -> Iterable["DateRange"]:
        if max_days < 1:
            raise ValueError(
                f"Date range cannot be split into chunks of {max_days} days."
            )

        max_size = timedelta(days=max_days - 1)
        current_start = self.start

        if current_start is not None and self.end is not None:
            while self.end - current_start > max_size:
                current_end = current_start + max_size
                yield DateRange(current_start, current_end)
                current_start = current_end + timedelta(days=1)

        yield DateRange(current_start, self.end)

    def _to_query_string(self) -> QueryString:
        return {
            "startDate": format_iso_date(self.start),
            "endDate": format_iso_date(self.end),
        }

__init__(start, end)

Creates the date range.

Parameters:

Name Type Description Default
start Optional[date]

The start date of the range (inclusive).

 required
end Optional[date]

The end date of the range (inclusive).

 required
Source code in signal_ocean/tonnage_list/models.py 
561
562
563
564
565
566
567
568
569
570
571
572
def __init__(self, start: Optional[date], end: Optional[date]):
    """Creates the date range.

    Args:
        start: The start date of the range (inclusive).
        end: The end date of the range (inclusive).
    """
    if start is not None and end is not None and end < start:
        raise ValueError("Start date cannot be after end date.")

    self.start = start
    self.end = end

FixtureType

Contains constants for available fixture types.

Source code in signal_ocean/tonnage_list/models.py 
545
546
547
548
549
550
551
552
553
554
555
class FixtureType(metaclass=IterableConstants):
    """Contains constants for available fixture types."""

    SCRAPED = "Scraped"
    """The fixture was scraped from an email."""

    MANUAL = "Manual"
    """The fixture was added manually."""

    IMPLIED = "Implied"
    """The fixture is implied by the vessel's AIS destination."""

IMPLIED = 'Implied' class-attribute instance-attribute

The fixture is implied by the vessel's AIS destination.

MANUAL = 'Manual' class-attribute instance-attribute

The fixture was added manually.

SCRAPED = 'Scraped' class-attribute instance-attribute

The fixture was scraped from an email.

HistoricalTonnageList

Bases: Sequence[TonnageList]

A historical tonnage list.

A historical tonnage list consists of a collection of tonnage lists, one for every day between the start and end date specified when querying the Historical Tonnage List API.

Source code in signal_ocean/tonnage_list/models.py 
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
class HistoricalTonnageList(Sequence[TonnageList]):
    """A historical tonnage list.

    A historical tonnage list consists of a collection of tonnage lists, one
    for every day between the start and end date specified when querying the
    Historical Tonnage List API.
    """

    def __init__(self, tonnage_lists: Iterable[TonnageList]):
        """Initializes the `HistoricalTonnageList`.

        Args:
            tonnage_lists: Tonnage lists per each day in the historical date
                range.
        """
        self.tonnage_lists = tuple(tonnage_lists)

    @overload
    def __getitem__(self, index: int) -> TonnageList:  # noqa: D105
        ...

    @overload
    def __getitem__(self, slice: slice) -> Sequence[TonnageList]:  # noqa: D105
        ...

    def __getitem__(
        self, i: Union[int, slice]
    ) -> Union[TonnageList, Sequence[TonnageList]]:  # noqa: D105
        return self.tonnage_lists.__getitem__(i)

    def __len__(self) -> int:  # noqa: D105
        return self.tonnage_lists.__len__()

    def __repr__(self) -> str:  # noqa: D105
        class_name = self.__class__.__name__
        return f"{class_name}(tonnage_lists={self.tonnage_lists!r})"

    def to_data_frame(self) -> pd.DataFrame:
        """Converts the Historical Tonnage List to a pandas data frame."""
        index_tuples = []
        data = []
        for tonnage_list in self.tonnage_lists:
            for vessel in tonnage_list.vessels:
                index_tuples.append((tonnage_list.date, vessel.imo))
                data.append(vessel._to_data_frame_row())

        data_frame = pd.DataFrame(
            data,
            index=pd.MultiIndex.from_tuples(
                index_tuples, names=[IndexLevel.DATE, IndexLevel.IMO]
            ),
            columns=list(Column),
        )

        return data_frame.astype(Column._get_data_types())  # type: ignore

__init__(tonnage_lists)

Initializes the HistoricalTonnageList.

Parameters:

Name Type Description Default
tonnage_lists Iterable[TonnageList]

Tonnage lists per each day in the historical date range.

 required
Source code in signal_ocean/tonnage_list/models.py 
699
700
701
702
703
704
705
706
def __init__(self, tonnage_lists: Iterable[TonnageList]):
    """Initializes the `HistoricalTonnageList`.

    Args:
        tonnage_lists: Tonnage lists per each day in the historical date
            range.
    """
    self.tonnage_lists = tuple(tonnage_lists)

to_data_frame()

Converts the Historical Tonnage List to a pandas data frame.

Source code in signal_ocean/tonnage_list/models.py 
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
def to_data_frame(self) -> pd.DataFrame:
    """Converts the Historical Tonnage List to a pandas data frame."""
    index_tuples = []
    data = []
    for tonnage_list in self.tonnage_lists:
        for vessel in tonnage_list.vessels:
            index_tuples.append((tonnage_list.date, vessel.imo))
            data.append(vessel._to_data_frame_row())

    data_frame = pd.DataFrame(
        data,
        index=pd.MultiIndex.from_tuples(
            index_tuples, names=[IndexLevel.DATE, IndexLevel.IMO]
        ),
        columns=list(Column),
    )

    return data_frame.astype(Column._get_data_types())  # type: ignore

IndexLevel

Contains constants for available data frame index levels.

Source code in signal_ocean/tonnage_list/data_frame.py 
229
230
231
232
233
234
235
236
class IndexLevel(metaclass=IterableConstants):
    """Contains constants for available data frame index levels."""

    DATE = "date"
    """The point in time at which the data was captured."""

    IMO = "imo"
    """The vessel's IMO number."""

DATE = 'date' class-attribute instance-attribute

The point in time at which the data was captured.

IMO = 'imo' class-attribute instance-attribute

The vessel's IMO number.

LocationTaxonomy

Contains constants for available location taxonomies.

Source code in signal_ocean/tonnage_list/models.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
class LocationTaxonomy(metaclass=IterableConstants):
    """Contains constants for available location taxonomies."""

    PORT = "Port"
    """A port."""

    COUNTRY = "Country"
    """A country."""

    NARROW_AREA = "Narrow Area"
    """A narrow geographical Area."""

    WIDE_AREA = "Wide Area"
    """A wide geographical area."""

COUNTRY = 'Country' class-attribute instance-attribute

A country.

NARROW_AREA = 'Narrow Area' class-attribute instance-attribute

A narrow geographical Area.

PORT = 'Port' class-attribute instance-attribute

A port.

WIDE_AREA = 'Wide Area' class-attribute instance-attribute

A wide geographical area.

MarketDeployment

Available market deployments.

Source code in signal_ocean/tonnage_list/models.py 
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
class MarketDeployment(metaclass=IterableConstants):
    """Available market deployments."""

    SPOT = "Spot"
    """Vessels controlled by commercial operators that participate in the spot
    market and are advertised through tonnage lists and reported fixtures.
    """

    PROGRAM = "Program"
    """Vessels that are controlled by charterers that do not participate in the
    spot market and are either not advertised through tonnage lists or tonnage
    lists report the fact that they participate in the program market.
    """

    RELET = "Relet"
    """Vessels controlled by charterers that participate in the spot market and
    are advertised through tonnage lists and reported fixtures.
    """

    CONTRACT = "Contract"
    """Vessels controlled by commercial operators that do not participate in
    the spot market and are typically carrying system cargoes with repetitive
    trading patterns.
    """

CONTRACT = 'Contract' class-attribute instance-attribute

Vessels controlled by commercial operators that do not participate in the spot market and are typically carrying system cargoes with repetitive trading patterns.

PROGRAM = 'Program' class-attribute instance-attribute

Vessels that are controlled by charterers that do not participate in the spot market and are either not advertised through tonnage lists or tonnage lists report the fact that they participate in the program market.

RELET = 'Relet' class-attribute instance-attribute

Vessels controlled by charterers that participate in the spot market and are advertised through tonnage lists and reported fixtures.

SPOT = 'Spot' class-attribute instance-attribute

Vessels controlled by commercial operators that participate in the spot market and are advertised through tonnage lists and reported fixtures.

OperationalStatus

Contains constants for available operational statuses.

Source code in signal_ocean/tonnage_list/models.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
class OperationalStatus(metaclass=IterableConstants):
    """Contains constants for available operational statuses."""

    BALLAST_FIXED = "Ballast Fixed"
    """The vessel is currently without cargo but fixed."""

    REPAIRS = "Repairs"
    """The vessel is undergoing repairs or is in dry dock."""

    WAITING_TO_LOAD = "Waiting to Load"
    """The vessel is waiting to load."""

    LOADING = "Loading"
    """The vessel is loading.

    This means the vessel has entered a jetty or is performing a ship-to-ship
    operation."""

    LADEN = "Laden"
    """The vesel has loaded."""

    WAITING_TO_DISCHARGE = "Waiting to Discharge"
    """The vessel is waiting to Discharge."""

    DISCHARGING = "Discharging"
    """The vessel is discharging.

    This means the vessel has entered a jetty or is performing a ship-to-ship
    operation."""

    ACTIVE_STORAGE = "Active Storage"
    """The vessel is in active storage.

    This means the vessel acts as short-term storage (in comparison to storage
    vessels).
    """

    BALLAST_UNFIXED = "Ballast Unfixed"
    """The vessel is currently without cargo and is not fixed (is prompt)."""

    BALLAST_FIXED_IMPLIED = "Ballast Fixed (implied)"
    """The vessel is currently without cargo and its AIS destination implies
    that it's fixed."""

ACTIVE_STORAGE = 'Active Storage' class-attribute instance-attribute

The vessel is in active storage.

This means the vessel acts as short-term storage (in comparison to storage vessels).

BALLAST_FIXED = 'Ballast Fixed' class-attribute instance-attribute

The vessel is currently without cargo but fixed.

BALLAST_FIXED_IMPLIED = 'Ballast Fixed (implied)' class-attribute instance-attribute

The vessel is currently without cargo and its AIS destination implies that it's fixed.

BALLAST_UNFIXED = 'Ballast Unfixed' class-attribute instance-attribute

The vessel is currently without cargo and is not fixed (is prompt).

DISCHARGING = 'Discharging' class-attribute instance-attribute

The vessel is discharging.

This means the vessel has entered a jetty or is performing a ship-to-ship operation.

LADEN = 'Laden' class-attribute instance-attribute

The vesel has loaded.

LOADING = 'Loading' class-attribute instance-attribute

The vessel is loading.

This means the vessel has entered a jetty or is performing a ship-to-ship operation.

REPAIRS = 'Repairs' class-attribute instance-attribute

The vessel is undergoing repairs or is in dry dock.

WAITING_TO_DISCHARGE = 'Waiting to Discharge' class-attribute instance-attribute

The vessel is waiting to Discharge.

WAITING_TO_LOAD = 'Waiting to Load' class-attribute instance-attribute

The vessel is waiting to load.

Port dataclass

A maritime facility where vessels can dock.

Attributes:

Name Type Description
id int

The ID of the port.
name str

The name of the port.
Source code in signal_ocean/tonnage_list/models.py 
309
310
311
312
313
314
315
316
317
318
319
@dataclass(frozen=True, eq=False)
class Port:
    """A maritime facility where vessels can dock.

    Attributes:
        id: The ID of the port.
        name: The name of the port.
    """

    id: int
    name: str

PortFilter dataclass

A filter used to find specific ports.

Attributes:

Name Type Description
name_like Optional[str]

Used to find ports by name. When specified, ports whose names partially match (contain) the attribute's value will be returned. Matching is case-insensitive.
Source code in signal_ocean/tonnage_list/models.py 
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
@dataclass(eq=False)
class PortFilter:
    """A filter used to find specific ports.

    Attributes:
        name_like: Used to find ports by name. When specified, ports whose
            names partially match (contain) the attribute's value will be
            returned. Matching is case-insensitive.
    """

    name_like: Optional[str] = None

    def _apply(self, ports: Iterable[Port]) -> Iterable[Port]:
        return filter(self.__does_port_match, ports)

    def __does_port_match(self, port: Port) -> bool:
        return not self.name_like or contains_caseless(
            self.name_like, port.name
        )

PushType

Available push types.

Source code in signal_ocean/tonnage_list/models.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
class PushType(metaclass=IterableConstants):
    """Available push types."""

    NOT_PUSHED = "Not Pushed"
    """Vessels that are not pushed anymore."""

    PUSHED_POSS = "Pushed POSS"
    """Vessels actively pushed in the market with notification "Poss".

    "Poss" stands for "Possibly", meaning that vessels marked with this type
    are a broker projection.
    """

    PUSHED = "Pushed"
    """Vessels actively pushed in the market through tonnage or position lists.
    """

NOT_PUSHED = 'Not Pushed' class-attribute instance-attribute

Vessels that are not pushed anymore.

PUSHED = 'Pushed' class-attribute instance-attribute

Vessels actively pushed in the market through tonnage or position lists.

PUSHED_POSS = 'Pushed POSS' class-attribute instance-attribute

Vessels actively pushed in the market with notification "Poss".

"Poss" stands for "Possibly", meaning that vessels marked with this type are a broker projection.

SourceType

Contains constants for available prediction source types.

Source code in signal_ocean/tonnage_list/models.py 
299
300
301
302
303
304
305
306
class SourceType(metaclass=IterableConstants):
    """Contains constants for available prediction source types."""

    SOURCE = "Source"
    """There is hard evidence backing the given prediction."""

    PREDICTION = "Prediction"
    """The prediction was made based on an algorithm."""

PREDICTION = 'Prediction' class-attribute instance-attribute

The prediction was made based on an algorithm.

SOURCE = 'Source' class-attribute instance-attribute

There is hard evidence backing the given prediction.

TonnageList

Bases: Sequence[Vessel]

A tonnage list as it occurred at a certain point in time.

Attributes:

Name Type Description
vessels

Vessels present in the tonnage list at the time it was captured. For more details see the Vessel class.
date

The date and time at which the tonnage list was captured.
Source code in signal_ocean/tonnage_list/models.py 
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
class TonnageList(Sequence[Vessel]):
    """A tonnage list as it occurred at a certain point in time.

    Attributes:
        vessels: Vessels present in the tonnage list at the time it was
            captured. For more details see the `Vessel` class.
        date: The date and time at which the tonnage list was captured.
    """

    def __init__(self, vessels: Iterable[Vessel], date: datetime):
        """Initializes the tonnage list.

        Args:
            vessels: Vessels present in the tonnage list at the time it was
                captured. For more details see the `Vessel` class.
            date: The date and time at which the tonnage list was captured.
        """
        self.vessels = tuple(vessels)
        self.date = date

    @overload
    def __getitem__(self, index: int) -> Vessel:  # noqa: D105
        ...

    @overload
    def __getitem__(self, slice: slice) -> Sequence[Vessel]:  # noqa: D105
        ...

    def __getitem__(
        self, i: Union[int, slice]
    ) -> Union[Vessel, Sequence[Vessel]]:  # noqa: D105
        return self.vessels.__getitem__(i)

    def __len__(self) -> int:  # noqa: D105
        return self.vessels.__len__()

    def __repr__(self) -> str:  # noqa: D105
        class_name = self.__class__.__name__
        return f"{class_name}(vessels={self.vessels!r})"

    def to_data_frame(self) -> pd.DataFrame:
        """Converts the tonnage list to a pandas data frame."""
        vessels_by_imo = {v.imo: v._to_data_frame_row() for v in self.vessels}
        data_frame = pd.DataFrame.from_dict(vessels_by_imo, orient="index", columns=list(Column))   # noqa
        data_frame.index.set_names(IndexLevel.IMO)

        return data_frame.astype(Column._get_data_types())  # type: ignore

__init__(vessels, date)

Initializes the tonnage list.

Parameters:

Name Type Description Default
vessels Iterable[Vessel]

Vessels present in the tonnage list at the time it was captured. For more details see the Vessel class.

 required
date datetime

The date and time at which the tonnage list was captured.

 required
Source code in signal_ocean/tonnage_list/models.py 
651
652
653
654
655
656
657
658
659
660
def __init__(self, vessels: Iterable[Vessel], date: datetime):
    """Initializes the tonnage list.

    Args:
        vessels: Vessels present in the tonnage list at the time it was
            captured. For more details see the `Vessel` class.
        date: The date and time at which the tonnage list was captured.
    """
    self.vessels = tuple(vessels)
    self.date = date

to_data_frame()

Converts the tonnage list to a pandas data frame.

Source code in signal_ocean/tonnage_list/models.py 
682
683
684
685
686
687
688
def to_data_frame(self) -> pd.DataFrame:
    """Converts the tonnage list to a pandas data frame."""
    vessels_by_imo = {v.imo: v._to_data_frame_row() for v in self.vessels}
    data_frame = pd.DataFrame.from_dict(vessels_by_imo, orient="index", columns=list(Column))   # noqa
    data_frame.index.set_names(IndexLevel.IMO)

    return data_frame.astype(Column._get_data_types())  # type: ignore

TonnageListAPI

Handles communication with Signal's Tonnage List API.

Source code in signal_ocean/tonnage_list/api.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 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
 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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
class TonnageListAPI:
    """Handles communication with Signal's Tonnage List API."""

    __MAX_DATE_RANGE_DAYS = 365

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

        Args:
            connection: API connection configuration. If not provided, the
                default connection method is used.
        """
        self.__connection = connection or Connection()

    def get_tonnage_list(
        self,
        loading_port: Port,
        vessel_class: VesselClass,
        laycan_end_in_days: Optional[int] = None,
        vessel_filter: Optional[VesselFilter] = None,
    ) -> TonnageList:
        """Retrieves a tonnage list.

        Args:
            loading_port: A loading port from which ETA will be calculated.
            vessel_class: The vessel class of vessels in the tonnage list.
            laycan_end_in_days: The maximum ETA expressed as a number of days
                from now.
            vessel_filter: A filter defining which vessels should be included
                in the response. See the `VesselFilter` class for details.

        Returns:
            Returns a `TonnageList` containing vessels that match the specified
            criteria.
        """
        query_string: QueryString = {
            "loadingPort": loading_port.id,
            "vesselClass": vessel_class.id,
            "laycanEndInDays": laycan_end_in_days,
            **(vessel_filter._to_query_string() if vessel_filter else {}),
        }

        response = self.__connection._make_get_request(
            "htl-api/tonnage-list/", query_string
        )

        response.raise_for_status()
        return _json.parse_tonnage_list_response(response.json())

    def get_historical_tonnage_list(
        self,
        loading_port: Port,
        vessel_class: VesselClass,
        laycan_end_in_days: Optional[int] = None,
        date_range: Optional[DateRange] = None,
        vessel_filter: Optional[VesselFilter] = None,
    ) -> HistoricalTonnageList:
        """Retrieves a historical tonnage list.

        If no input dates are provided, the last 10 days will be fetched
        (including today).

        To get a tonnage list for a specific day, set both date parameters to
        the desired date.

        Args:
            loading_port: A loading port from which ETA will be calculated.
            vessel_class: The vessel class of vessels in the tonnage list.
            laycan_end_in_days: The maximum ETA expressed as a number of days
                after the end date.
            date_range: A range of dates for which to get historical tonnage
                lists.
            vessel_filter: A filter defining which vessels should be included
                in the response. See `VesselFilter` class for details.

        Returns:
            Given a time-range, returns a `HistoricalTonnageList` containing a
            `TonnageList` for every day between the start and end dates.
        """
        date_ranges = (date_range or DateRange(start=None, end=None))._split(
            TonnageListAPI.__MAX_DATE_RANGE_DAYS
        )

        tonnage_lists = (
            tonnage_list
            for dr in date_ranges
            for tonnage_list in self._get_htl_chunk(
                loading_port,
                vessel_class,
                dr,
                laycan_end_in_days,
                vessel_filter,
            )
        )

        return HistoricalTonnageList(tonnage_lists)

    def _get_htl_chunk(
        self,
        loading_port: Port,
        vessel_class: VesselClass,
        date_range: DateRange,
        laycan_end_in_days: Optional[int] = None,
        vessel_filter: Optional[VesselFilter] = None,
    ) -> HistoricalTonnageList:
        query_string: QueryString = {
            "loadingPort": loading_port.id,
            "vesselClass": vessel_class.id,
            "laycanEndInDays": laycan_end_in_days,
            **date_range._to_query_string(),
            **(vessel_filter._to_query_string() if vessel_filter else {}),
        }

        response = self.__connection._make_get_request(
            "htl-api/historical-tonnage-list/", query_string
        )

        response.raise_for_status()
        return _json.parse_historical_tonnage_list_response(response.json())

    def get_ports(
        self, port_filter: Optional[PortFilter] = None
    ) -> Tuple[Port, ...]:
        """Retrieves available ports.

        Args:
            port_filter: A filter used to find specific ports. If not
                specified, returns all available ports.

        Returns:
            A tuple of available ports that match the filter.
        """
        response = self.__connection._make_get_request(
            "htl-api/historical-tonnage-list/ports"
        )
        response.raise_for_status()

        ports = (Port(**p) for p in response.json())
        port_filter = port_filter or PortFilter()

        return tuple(port_filter._apply(ports))

    def get_vessel_classes(
        self, class_filter: Optional[VesselClassFilter] = None
    ) -> Tuple[VesselClass, ...]:
        """Retrieves available vessel classes.

        Args:
            class_filter: A filter used to find specific vessel classes. If not
                specified, returns all available vessel classes.

        Returns:
            A tuple of available vessel classes that match the filter.
        """
        response = self.__connection._make_get_request(
            "htl-api/historical-tonnage-list/vessel-classes"
        )
        response.raise_for_status()

        classes = (VesselClass(**c) for c in response.json())
        class_filter = class_filter or VesselClassFilter()

        return tuple(class_filter._apply(classes))

__init__(connection=None)

Initializes TonnageListAPI.

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/tonnage_list/api.py 
25
26
27
28
29
30
31
32
def __init__(self, connection: Optional[Connection] = None):
    """Initializes `TonnageListAPI`.

    Args:
        connection: API connection configuration. If not provided, the
            default connection method is used.
    """
    self.__connection = connection or Connection()

get_historical_tonnage_list(loading_port, vessel_class, laycan_end_in_days=None, date_range=None, vessel_filter=None)

Retrieves a historical tonnage list.

If no input dates are provided, the last 10 days will be fetched (including today).

To get a tonnage list for a specific day, set both date parameters to the desired date.

Parameters:

Name Type Description Default
loading_port Port

A loading port from which ETA will be calculated.

 required
vessel_class VesselClass

The vessel class of vessels in the tonnage list.

 required
laycan_end_in_days Optional[int]

The maximum ETA expressed as a number of days after the end date.

 None
date_range Optional[DateRange]

A range of dates for which to get historical tonnage lists.

 None
vessel_filter Optional[VesselFilter]

A filter defining which vessels should be included in the response. See VesselFilter class for details.

 None

Returns:

Type Description
HistoricalTonnageList

Given a time-range, returns a HistoricalTonnageList containing a
HistoricalTonnageList

TonnageList for every day between the start and end dates.
Source code in signal_ocean/tonnage_list/api.py 
 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
def get_historical_tonnage_list(
    self,
    loading_port: Port,
    vessel_class: VesselClass,
    laycan_end_in_days: Optional[int] = None,
    date_range: Optional[DateRange] = None,
    vessel_filter: Optional[VesselFilter] = None,
) -> HistoricalTonnageList:
    """Retrieves a historical tonnage list.

    If no input dates are provided, the last 10 days will be fetched
    (including today).

    To get a tonnage list for a specific day, set both date parameters to
    the desired date.

    Args:
        loading_port: A loading port from which ETA will be calculated.
        vessel_class: The vessel class of vessels in the tonnage list.
        laycan_end_in_days: The maximum ETA expressed as a number of days
            after the end date.
        date_range: A range of dates for which to get historical tonnage
            lists.
        vessel_filter: A filter defining which vessels should be included
            in the response. See `VesselFilter` class for details.

    Returns:
        Given a time-range, returns a `HistoricalTonnageList` containing a
        `TonnageList` for every day between the start and end dates.
    """
    date_ranges = (date_range or DateRange(start=None, end=None))._split(
        TonnageListAPI.__MAX_DATE_RANGE_DAYS
    )

    tonnage_lists = (
        tonnage_list
        for dr in date_ranges
        for tonnage_list in self._get_htl_chunk(
            loading_port,
            vessel_class,
            dr,
            laycan_end_in_days,
            vessel_filter,
        )
    )

    return HistoricalTonnageList(tonnage_lists)

get_ports(port_filter=None)

Retrieves available ports.

Parameters:

Name Type Description Default
port_filter Optional[PortFilter]

A filter used to find specific ports. If not specified, returns all available ports.

 None

Returns:

Type Description
Tuple[Port, ...]

A tuple of available ports that match the filter.
Source code in signal_ocean/tonnage_list/api.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def get_ports(
    self, port_filter: Optional[PortFilter] = None
) -> Tuple[Port, ...]:
    """Retrieves available ports.

    Args:
        port_filter: A filter used to find specific ports. If not
            specified, returns all available ports.

    Returns:
        A tuple of available ports that match the filter.
    """
    response = self.__connection._make_get_request(
        "htl-api/historical-tonnage-list/ports"
    )
    response.raise_for_status()

    ports = (Port(**p) for p in response.json())
    port_filter = port_filter or PortFilter()

    return tuple(port_filter._apply(ports))

get_tonnage_list(loading_port, vessel_class, laycan_end_in_days=None, vessel_filter=None)

Retrieves a tonnage list.

Parameters:

Name Type Description Default
loading_port Port

A loading port from which ETA will be calculated.

 required
vessel_class VesselClass

The vessel class of vessels in the tonnage list.

 required
laycan_end_in_days Optional[int]

The maximum ETA expressed as a number of days from now.

 None
vessel_filter Optional[VesselFilter]

A filter defining which vessels should be included in the response. See the VesselFilter class for details.

 None

Returns:

Type Description
TonnageList

Returns a TonnageList containing vessels that match the specified
TonnageList

criteria.
Source code in signal_ocean/tonnage_list/api.py 
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
def get_tonnage_list(
    self,
    loading_port: Port,
    vessel_class: VesselClass,
    laycan_end_in_days: Optional[int] = None,
    vessel_filter: Optional[VesselFilter] = None,
) -> TonnageList:
    """Retrieves a tonnage list.

    Args:
        loading_port: A loading port from which ETA will be calculated.
        vessel_class: The vessel class of vessels in the tonnage list.
        laycan_end_in_days: The maximum ETA expressed as a number of days
            from now.
        vessel_filter: A filter defining which vessels should be included
            in the response. See the `VesselFilter` class for details.

    Returns:
        Returns a `TonnageList` containing vessels that match the specified
        criteria.
    """
    query_string: QueryString = {
        "loadingPort": loading_port.id,
        "vesselClass": vessel_class.id,
        "laycanEndInDays": laycan_end_in_days,
        **(vessel_filter._to_query_string() if vessel_filter else {}),
    }

    response = self.__connection._make_get_request(
        "htl-api/tonnage-list/", query_string
    )

    response.raise_for_status()
    return _json.parse_tonnage_list_response(response.json())

get_vessel_classes(class_filter=None)

Retrieves available vessel classes.

Parameters:

Name Type Description Default
class_filter Optional[VesselClassFilter]

A filter used to find specific vessel classes. If not specified, returns all available vessel classes.

 None

Returns:

Type Description
Tuple[VesselClass, ...]

A tuple of available vessel classes that match the filter.
Source code in signal_ocean/tonnage_list/api.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def get_vessel_classes(
    self, class_filter: Optional[VesselClassFilter] = None
) -> Tuple[VesselClass, ...]:
    """Retrieves available vessel classes.

    Args:
        class_filter: A filter used to find specific vessel classes. If not
            specified, returns all available vessel classes.

    Returns:
        A tuple of available vessel classes that match the filter.
    """
    response = self.__connection._make_get_request(
        "htl-api/historical-tonnage-list/vessel-classes"
    )
    response.raise_for_status()

    classes = (VesselClass(**c) for c in response.json())
    class_filter = class_filter or VesselClassFilter()

    return tuple(class_filter._apply(classes))

Vessel dataclass

Holds information for a vessel that's present in a TonnageList.

Contains both static and point-in-time vessel data. When converted to a data frame, all point-in-time data is suffixed with _point_in_time. See the Column class for the available data frame column names.

Attributes:

Name Type Description
imo int

The vessel's IMO number.
name str

The vessel's name.
vessel_class str

Name of the vessel class the vessel is categorized as.
ice_class Optional[str]

The vessel's ice class.
year_built int

The year the vessel has been built.
deadweight int

The vessel's deadweight.
length_overall float

The vessel's length overall.
breadth_extreme int

The vessel's breadth extreme.
market_deployment str

Market deployment of the vessel at the tonnage lists' point in time. See the MarketDeployment class for available values.
push_type str

Push type of the vessel at the tonnage lists' point in time. See the PushType class for available values.
open_port_id int

The vessel's open port id at the tonnage lists' point in time.
open_port str

The vessel's open port name at the tonnage lists' point in time.
open_date Optional[datetime]

The vessel's open date at the tonnage lists' point in time.
operational_status str

Operational status of the vessel at the tonnage lists' point in time. See the OperationalStatus class for available values.
commercial_operator_id int

The vessel's commercial operator id at the tonnage lists' point in time.
commercial_operator str

The vessel's commercial operator at the tonnage lists' point in time.
commercial_status str

Commercial status of the vessel at the tonnage lists' point in time. See the CommercialStatus class for available values.
eta Optional[datetime]

Estimated time of arrival at the tonnage lists' point in time.
latest_ais Optional[datetime]

Timestamp of the vessel's latest AIS information at the tonnage lists' point in time.
subclass str

The vessel's subclass. See the VesselSubclass class for available values.
willing_to_switch_subclass bool

When True, the vessel is willing to switch its subclass.
open_prediction_accuracy str

How accurate, in terms of location taxonomy, is the vessel's open prediction at the tonnage lists' point in time. See the LocationTaxonomy class for available values.
open_areas Tuple[Area, ...]

A hierarchical collection of areas the vessel opens at at the tonnage lists' point in time.

If a vessel opens at a specific port, this attribute will contain areas containing the port. For example, the continent, wide/narrow areas, country, etc.
availability_port_type str

Prediction source of the vessel's open port at the tonnage lists' point in time. See the SourceType class for possible values.
availability_date_type str

Prediction source of the vessel's open date at the tonnage lists' point in time. See the SourceType class for possible values.
fixture_type str

Fixture type. One of Scraped, Manual, Implied
current_vessel_sub_type_id int

Current vessel sub type Id
current_vessel_sub_type str

One of: -1: Unknown, 1: Dirty, 2: Clean
willing_to_switch_current_vessel_sub_type bool

bool nullable. If the vessel is willing to compete on a different vessel subclass category or not.
Source code in signal_ocean/tonnage_list/models.py 
 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
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
193
194
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
223
224
225
226
227
228
229
230
@dataclass(frozen=True, eq=False)
class Vessel:
    """Holds information for a vessel that's present in a `TonnageList`.

    Contains both static and point-in-time vessel data. When converted to a
    data frame, all point-in-time data is suffixed with `_point_in_time`. See
    the `Column` class for the available data frame column names.

    Attributes:
        imo: The vessel's IMO number.
        name: The vessel's name.
        vessel_class: Name of the vessel class the vessel is categorized as.
        ice_class: The vessel's ice class.
        year_built: The year the vessel has been built.
        deadweight: The vessel's deadweight.
        length_overall: The vessel's length overall.
        breadth_extreme: The vessel's breadth extreme.
        market_deployment: Market deployment of the vessel at the tonnage
            lists' point in time. See the `MarketDeployment` class for
            available values.
        push_type: Push type of the vessel at the tonnage lists' point in time.
            See the `PushType` class for available values.
        open_port_id: The vessel's open port id at the tonnage lists' point in
            time.
        open_port: The vessel's open port name at the tonnage lists' point in
            time.
        open_date: The vessel's open date at the tonnage lists' point in time.
        operational_status: Operational status of the vessel at the tonnage
            lists' point in time. See the `OperationalStatus` class for
            available values.
        commercial_operator_id: The vessel's commercial operator id
            at the tonnage lists' point in time.
        commercial_operator: The vessel's commercial operator at the tonnage
            lists' point in time.
        commercial_status: Commercial status of the vessel at the tonnage
            lists' point in time. See the `CommercialStatus` class for
            available values.
        eta: Estimated time of arrival at the tonnage lists' point in time.
        latest_ais: Timestamp of the vessel's latest AIS information at the
            tonnage lists' point in time.
        subclass: The vessel's subclass. See the `VesselSubclass` class for
            available values.
        willing_to_switch_subclass: When `True`, the vessel is willing to
            switch its subclass.
        open_prediction_accuracy: How accurate, in terms of location taxonomy,
            is the vessel's open prediction at the tonnage lists' point in
            time. See the `LocationTaxonomy` class for available values.
        open_areas: A hierarchical collection of areas the vessel opens at at
            the tonnage lists' point in time.

            If a vessel opens at a specific port, this attribute
            will contain areas containing the port. For example, the continent,
            wide/narrow areas, country, etc.
        availability_port_type: Prediction source of the vessel's open port at
            the tonnage lists' point in time. See the `SourceType` class for
            possible values.
        availability_date_type: Prediction source of the vessel's open date at
            the tonnage lists' point in time. See the `SourceType` class for
            possible values.
        fixture_type: Fixture type. One of Scraped, Manual, Implied
        current_vessel_sub_type_id:  Current vessel sub type Id
        current_vessel_sub_type:  One of: -1: Unknown, 1: Dirty, 2: Clean
        willing_to_switch_current_vessel_sub_type: bool nullable. If the vessel
            is willing to compete on a different vessel subclass
            category or not.
    """

    imo: int
    name: str
    vessel_class: str
    ice_class: Optional[str]
    year_built: int
    deadweight: int
    length_overall: float
    breadth_extreme: int
    market_deployment: str
    push_type: str
    open_port_id: int
    open_port: str
    open_date: Optional[datetime]
    operational_status: str
    commercial_operator_id: int
    commercial_operator: str
    commercial_status: str
    eta: Optional[datetime]
    latest_ais: Optional[datetime]
    subclass: str
    willing_to_switch_subclass: bool
    open_prediction_accuracy: str
    open_areas: Tuple[Area, ...]
    availability_port_type: str
    availability_date_type: str
    fixture_type: str
    current_vessel_sub_type_id: int
    current_vessel_sub_type: str
    willing_to_switch_current_vessel_sub_type: bool

    def __post_init__(self) -> None:  # noqa: D105
        if self.open_areas is None:
            object.__setattr__(self, "open_areas", tuple())

    @property
    def open_country(self) -> Optional[str]:
        """The vessel's open country name.

        Returns:
            The name of the open country or `None` if an area with
            `LocationTaxonomy.COUNTRY` was not present.
        """
        return self.__area_name_by_taxonomy(LocationTaxonomy.COUNTRY)

    @property
    def open_narrow_area(self) -> Optional[str]:
        """The vessel's narrow open area name.

        Returns:
            The name of the narrow open area or `None` if an area with
            `LocationTaxonomy.NARROW_AREA` was not present.
        """
        return self.__area_name_by_taxonomy(LocationTaxonomy.NARROW_AREA)

    @property
    def open_wide_area(self) -> Optional[str]:
        """The vessel's wide open area name.

        Returns:
            The name of the wide open area or `None` if an area with
            `LocationTaxonomy.WIDE_AREA` was not present.
        """
        return self.__area_name_by_taxonomy(LocationTaxonomy.WIDE_AREA)

    def __area_name_by_taxonomy(self, taxonomy: str) -> Optional[str]:
        for a in self.open_areas:
            if a.location_taxonomy == taxonomy:
                return a.name
        return None

    def _to_data_frame_row(self) -> DataFrameRow:
        return Column._create_row(
            name=self.name,
            vessel_class=self.vessel_class,
            ice_class=self.ice_class,
            year_built=self.year_built,
            deadweight=self.deadweight,
            length_overall=self.length_overall,
            breadth_extreme=self.breadth_extreme,
            subclass=self.subclass,
            market_deployment=self.market_deployment,
            push_type=self.push_type,
            open_port_id=self.open_port_id,
            open_port=self.open_port,
            open_date=self.open_date,
            operational_status=self.operational_status,
            commercial_operator_id=self.commercial_operator_id,
            commercial_operator=self.commercial_operator,
            commercial_status=self.commercial_status,
            eta=self.eta,
            latest_ais=self.latest_ais,
            open_prediction_accuracy=self.open_prediction_accuracy,
            open_country=self.open_country,
            open_narrow_area=self.open_narrow_area,
            open_wide_area=self.open_wide_area,
            availability_port_type=self.availability_port_type,
            availability_date_type=self.availability_date_type,
            fixture_type=self.fixture_type,
            current_vessel_sub_type_id=self.current_vessel_sub_type_id,
            current_vessel_sub_type=self.availability_date_type,
            willing_to_switch_current_vessel_sub_type=self
            .willing_to_switch_current_vessel_sub_type
        )

open_country: Optional[str] property

The vessel's open country name.

Returns:

Type Description
Optional[str]

The name of the open country or None if an area with
Optional[str]

LocationTaxonomy.COUNTRY was not present.

open_narrow_area: Optional[str] property

The vessel's narrow open area name.

Returns:

Type Description
Optional[str]

The name of the narrow open area or None if an area with
Optional[str]

LocationTaxonomy.NARROW_AREA was not present.

open_wide_area: Optional[str] property

The vessel's wide open area name.

Returns:

Type Description
Optional[str]

The name of the wide open area or None if an area with
Optional[str]

LocationTaxonomy.WIDE_AREA was not present.

VesselClass dataclass

A group of vessels of similar characteristics, i.e. Aframax, Panamax, etc.

Attributes:

Name Type Description
id int

The vessel class ID.
name str

The vessel class name.
Source code in signal_ocean/tonnage_list/models.py 
322
323
324
325
326
327
328
329
330
331
332
@dataclass(frozen=True, eq=False)
class VesselClass:
    """A group of vessels of similar characteristics, i.e. Aframax, Panamax, etc.

    Attributes:
        id: The vessel class ID.
        name: The vessel class name.
    """

    id: int
    name: str

VesselClassFilter dataclass

A filter used to find specific vessel classes.

Attributes:

Name Type Description
name_like Optional[str]

Used to find vessel classes by name. When specified, vessel classes whose names partially match (contain) the attribute's value will be returned. Matching is case-insensitive.
Source code in signal_ocean/tonnage_list/models.py 
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
@dataclass(eq=False)
class VesselClassFilter:
    """A filter used to find specific vessel classes.

    Attributes:
        name_like: Used to find vessel classes by name. When specified, vessel
            classes whose names partially match (contain) the attribute's value
            will be returned. Matching is case-insensitive.
    """

    name_like: Optional[str] = None

    def _apply(
        self, vessel_classes: Iterable[VesselClass]
    ) -> Iterable[VesselClass]:
        return filter(self.__does_class_match, vessel_classes)

    def __does_class_match(self, vessel_class: VesselClass) -> bool:
        return not self.name_like or contains_caseless(
            self.name_like, vessel_class.name
        )

VesselFilter dataclass

Used to filter vessels when retrieving tonnage lists.

All attributes in this class are optional, i.e. no filtering will be performed on attributes whose value is None.

Attributes that accept a list of values are used to perform an OR comparison. In other words, when a non-empty list of values is used, the tonnage lists will contain vessels that match on any of the specified values. Using an empty list will result in no filtering being performed.

VesselFilter is mutable in order to allow making adjustments to existing instances if query results are unsatisfactory.

Attributes:

Name Type Description
push_types Optional[List[str]]

Return vessels with the specified push types. Use constants defined in the PushType class as values of this attribute.
market_deployments Optional[List[str]]

Return vessels with the specified market deployment types. Use constants defined in the MarketDeployment class as values of this attribute.
commercial_statuses Optional[List[str]]

Return vessels with the specified commercial statuses. Use constants defined in the CommercialStatus class for the values of this attribute.
vessel_subclass Optional[str]

Return vessels of the specified subclass. Use constants defined in the VesselSubclass class for the values of this attribute.
add_willing_to_switch_subclass Optional[bool]

When True, returns vessels that do not match the subclass but are willing to switch to it.
latest_ais_since Optional[int]

The maximum age, in days, of the vessel's AIS information at the time the tonnage list was captured.
operational_statuses Optional[List[str]]

Return vessels with the specified operational statuses. Use constants defined in the OperationalStatus class for the values of this attribute.
min_liquid_capacity Optional[int]

The minimum liquid capacity, in cubic meters, the vessel should be able to hold.
max_liquid_capacity Optional[int]

The maximum liquid capacity, in cubic meters, the vessel should be able to hold.
fixture_types Optional[List[str]]

Return vessels with the specified fixture types. Use constants defined in the FixtureType class for the values of this attribute.
last_cargo_types Optional[List[str]]

Return vessels with the specified last cargo type IDs.
past_port_visits Optional[List[int]]

Return vessels with the specified past port visits.
open_port_ids Optional[List[int]]

Return vessels with the specified open port ids.
canakkale_cancelling Optional[date]

Return vessels with the specified Canakkale cancelling date.
open_date Optional[date]

Return vessels with the specified open date.
ice_classes Optional[List[str]]

Return vessels with the specified ice classes.
min_cranes_ton_capacity Optional[int]

Return vessels with the specified minimum cranes ton capacity.
max_cranes_ton_capacity Optional[int]

Return vessels with the specified maximum cranes ton capacity.
min_length_overall Optional[int]

Return vessels with the specified minimum length overall.
max_length_overall Optional[int]

Return vessels with the specified maximum length overall.
min_breadth_extreme Optional[int]

Return vessels with the specified minimum breadth extreme.
max_breadth_extreme Optional[int]

Return vessels with the specified maximum breadth extreme.
openAreas Optional[int]

Return vessels with the specified open area ids.
openCountries Optional[int]

Return vessels with the specified open country ids.
Source code in signal_ocean/tonnage_list/models.py 
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
@dataclass(eq=False)
class VesselFilter:
    """Used to filter vessels when retrieving tonnage lists.

    All attributes in this class are optional, i.e. no filtering will be
    performed on attributes whose value is None.

    Attributes that accept a list of values are used to perform an *OR*
    comparison. In other words, when a non-empty list of values is used, the
    tonnage lists will contain vessels that match on **any** of the specified
    values. Using an empty list will result in no filtering being performed.

    `VesselFilter` is mutable in order to allow making adjustments to existing
    instances if query results are unsatisfactory.

    Attributes:
        push_types: Return vessels with the specified push types. Use constants
            defined in the `PushType` class as values of this
            attribute.
        market_deployments: Return vessels with the specified market deployment
            types. Use constants defined in the `MarketDeployment`
            class as values of this attribute.
        commercial_statuses: Return vessels with the specified
            commercial statuses. Use constants defined in the
            `CommercialStatus` class for the values of this attribute.
        vessel_subclass: Return vessels of the specified subclass.
            Use constants defined in the `VesselSubclass` class for the values
            of this attribute.
        add_willing_to_switch_subclass: When True, returns vessels
            that do not match the subclass but are willing to switch to it.
        latest_ais_since: The maximum age, in days, of the vessel's
            AIS information at the time the tonnage list was captured.
        operational_statuses: Return vessels with the specified
            operational statuses. Use constants defined in the
            `OperationalStatus` class for the values of this attribute.
        min_liquid_capacity: The minimum liquid capacity, in cubic
            meters, the vessel should be able to hold.
        max_liquid_capacity: The maximum liquid capacity, in cubic
            meters, the vessel should be able to hold.
        fixture_types: Return vessels with the specified
            fixture types. Use constants defined in the `FixtureType` class for
            the values of this attribute.
        last_cargo_types: Return vessels with the specified last
            cargo type IDs.
        past_port_visits: Return vessels with the specified past
            port visits.
        open_port_ids: Return vessels with the specified open
            port ids.
        canakkale_cancelling: Return vessels with the specified
            Canakkale cancelling date.
        open_date: Return vessels with the specified open date.
        ice_classes: Return vessels with the specified ice classes.
        min_cranes_ton_capacity: Return vessels with the specified
            minimum cranes ton capacity.
        max_cranes_ton_capacity: Return vessels with the specified
            maximum cranes ton capacity.
        min_length_overall: Return vessels with the specified
            minimum length overall.
        max_length_overall: Return vessels with the specified
            maximum length overall.
        min_breadth_extreme: Return vessels with the specified
            minimum breadth extreme.
        max_breadth_extreme: Return vessels with the specified
            maximum breadth extreme.
        openAreas: Return vessels with the specified open area ids.
        openCountries: Return vessels with the specified open
            country ids.
    """

    push_types: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    market_deployments: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    commercial_statuses: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    vessel_subclass: Optional[str] = VesselSubclass.ALL
    add_willing_to_switch_subclass: Optional[bool] = False
    latest_ais_since: Optional[int] = None
    operational_statuses: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    min_liquid_capacity: Optional[int] = None
    max_liquid_capacity: Optional[int] = None
    fixture_types: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    past_port_visits: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )
    open_port_ids: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )
    canakkale_cancelling: Optional[date] = None
    open_date: Optional[date] = None
    ice_classes: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    min_cranes_ton_capacity: Optional[int] = None
    max_cranes_ton_capacity: Optional[int] = None
    min_length_overall: Optional[int] = None
    max_length_overall: Optional[int] = None
    min_breadth_extreme: Optional[int] = None
    max_breadth_extreme: Optional[int] = None
    open_area_ids: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )
    open_country_ids: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )

    def _to_query_string(self) -> QueryString:
        return {
            "pushType": self.push_types,
            "commercialStatus": self.commercial_statuses,
            "latestAisSince": self.latest_ais_since,
            "vesselSubclass": self.vessel_subclass,
            "addWillingToSwitchSubclass": self.add_willing_to_switch_subclass,
            "marketDeployment": self.market_deployments,
            "operationalStatus": self.operational_statuses,
            "minLiquidCapacity": self.min_liquid_capacity,
            "maxLiquidCapacity": self.max_liquid_capacity,
            "fixtureType": self.fixture_types,
            "pastPortVisit": self.past_port_visits,
            "openPortId": self.open_port_ids,
            "canakkaleCancelling": format_iso_date(self.canakkale_cancelling),
            "openDate": format_iso_date(self.open_date),
            "iceClass": self.ice_classes,
            "cranesTonCapacityMin": self.min_cranes_ton_capacity,
            "cranesTonCapacityMax": self.max_cranes_ton_capacity,
            "lengthOverallMin": self.min_length_overall,
            "lengthOverallMax": self.max_length_overall,
            "breadthExtremeMin": self.min_breadth_extreme,
            "breadthExtremeMax": self.max_breadth_extreme,
            "openArea": self.open_area_ids,
            "openCountry": self.open_country_ids,
        }

VesselSubclass

Available vessel subclasses.

Source code in signal_ocean/tonnage_list/models.py 
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
class VesselSubclass(metaclass=IterableConstants):
    """Available vessel subclasses."""

    ALL = None
    """All vessel subclasses.

    Refers to all vessels without any classification regarding the cargo type
    they car carry.
    """

    DIRTY = "Dirty"
    """Vessels carrying dirty types of oil.

    Refers to all vessels that classify as carriers of dirty types of oil.
    Applies only to tankers.
    """

    CLEAN = "Clean"
    """Vessels carrying clean oil.

    Refers to all vessels that classify as carriers of clean types of oil.
    Applies only to tankers.
    """

ALL = None class-attribute instance-attribute

All vessel subclasses.

Refers to all vessels without any classification regarding the cargo type they car carry.

CLEAN = 'Clean' class-attribute instance-attribute

Vessels carrying clean oil.

Refers to all vessels that classify as carriers of clean types of oil. Applies only to tankers.

DIRTY = 'Dirty' class-attribute instance-attribute

Vessels carrying dirty types of oil.

Refers to all vessels that classify as carriers of dirty types of oil. Applies only to tankers.