nautical package

Subpackages

Submodules

nautical.exceptions module

Custom exception hierarchy for the nautical package.

This module defines domain-specific exceptions that provide better error messages and allow for more precise error handling than generic Python exceptions.

Exception Hierarchy:: NauticalError (base) ├── DataError │ ├── InvalidBuoyDataError │ │ ├── InvalidWindDataError │ │ ├── InvalidLocationDataError │ │ └── InvalidTimeDataError │ ├── InvalidSourceDataError │ └── ParsingError │ ├── CDataParsingError │ └── JSONParsingError ├── ConversionError │ ├── InvalidUnitsError │ ├── UnitMismatchError │ └── UnsupportedConversionError ├── NetworkError │ ├── BuoyNotFoundError │ ├── NOAAServiceError │ └── NetworkTimeoutError ├── CacheError │ ├── CacheNotFoundError │ ├── CacheWriteError │ └── CacheReadError └── LocationError

├── InvalidCoordinatesError ├── OutOfBoundsError └── DistanceCalculationError

exception nautical.exceptions.NauticalError[source]

Bases: Exception

Base exception for all nautical package errors.

All custom exceptions in the nautical package inherit from this class, allowing users to catch all nautical-specific errors with a single except clause.

exception nautical.exceptions.DataError[source]

Bases: NauticalError

Base exception for data validation and parsing errors.

exception nautical.exceptions.InvalidBuoyDataError(message: str, station: str | None = None, field: str | None = None)[source]

Bases: DataError, ValueError

Raised when buoy data is invalid or cannot be parsed.

This exception inherits from ValueError for backward compatibility.

station: The buoy station ID (if available)

field: The specific field that caused the error (if applicable)

__init__(message: str, station: str | None = None, field: str | None = None) → None[source]

exception nautical.exceptions.InvalidWindDataError(message: str, station: str | None = None, field: str | None = None)[source]

Bases: InvalidBuoyDataError

Raised when wind data cannot be parsed or is invalid.

Examples

Missing wind speed value
Invalid wind direction format
Gust data in unexpected format

exception nautical.exceptions.InvalidLocationDataError(message: str, station: str | None = None, field: str | None = None)[source]

Bases: InvalidBuoyDataError

Raised when location/coordinate data is invalid.

Examples

Missing latitude or longitude
Invalid coordinate format
Coordinates with wrong sign indicators

exception nautical.exceptions.InvalidTimeDataError(message: str, station: str | None = None, field: str | None = None)[source]

Bases: InvalidBuoyDataError

Raised when time/date data cannot be parsed.

Examples

Malformed timestamp
Missing date components
Invalid time format

exception nautical.exceptions.InvalidSourceDataError(message: str, source_name: str | None = None)[source]

Bases: DataError, ValueError

Raised when source data is invalid or cannot be parsed.

source_name: Name of the source (if available)

__init__(message: str, source_name: str | None = None) → None[source]

exception nautical.exceptions.ParsingError[source]

Bases: DataError

Base exception for parsing failures.

exception nautical.exceptions.CDataParsingError(message: str, raw_data: str | None = None)[source]

Bases: ParsingError

Raised when CDATA (HTML comment data) cannot be parsed.

raw_data: The raw CDATA that failed to parse (truncated if too long)

__init__(message: str, raw_data: str | None = None) → None[source]

exception nautical.exceptions.JSONParsingError[source]

Bases: ParsingError, ValueError

Raised when JSON data cannot be parsed.

This exception inherits from ValueError for backward compatibility with json.loads() error handling patterns.

exception nautical.exceptions.ConversionError[source]

Bases: NauticalError

Base exception for unit conversion errors.

exception nautical.exceptions.InvalidUnitsError(message: str, unit: object | None = None, valid_units: list | None = None)[source]

Bases: ConversionError, KeyError

Raised when an unknown or invalid unit type is used.

This exception inherits from KeyError for backward compatibility.

unit: The invalid unit that was provided

valid_units: List of valid units for the given type (if available)

__init__(message: str, unit: object | None = None, valid_units: list | None = None) → None[source]

exception nautical.exceptions.UnitMismatchError(message: str, from_unit: object | None = None, to_unit: object | None = None)[source]

Bases: ConversionError, TypeError

Raised when trying to convert between incompatible unit types.

For example, trying to convert temperature units to distance units.

This exception inherits from TypeError for backward compatibility.

from_unit: The source unit type

to_unit: The target unit type

__init__(message: str, from_unit: object | None = None, to_unit: object | None = None) → None[source]

exception nautical.exceptions.UnsupportedConversionError[source]

Bases: ConversionError

Raised when a conversion is not supported.

This is different from UnitMismatchError - the units may be compatible types, but the specific conversion is not implemented.

exception nautical.exceptions.NetworkError[source]

Bases: NauticalError

Base exception for network and web scraping errors.

exception nautical.exceptions.BuoyNotFoundError(message: str, station: str | None = None, url: str | None = None)[source]

Bases: NetworkError, ValueError

Raised when a buoy station cannot be found.

This typically occurs when an invalid buoy ID is provided or when NOAA doesn’t have data for the requested station.

station: The buoy station ID that was not found

url: The URL that was attempted (if available)

__init__(message: str, station: str | None = None, url: str | None = None) → None[source]

exception nautical.exceptions.NOAAServiceError(message: str, url: str | None = None, status_code: int | None = None, original_error: Exception | None = None)[source]

Bases: NetworkError

Raised when the NOAA service is unavailable or returns an error.

url: The URL that failed

status_code: HTTP status code (if available)

original_error: The underlying exception

__init__(message: str, url: str | None = None, status_code: int | None = None, original_error: Exception | None = None) → None[source]

exception nautical.exceptions.NetworkTimeoutError(message: str, url: str | None = None, timeout: float | None = None)[source]

Bases: NetworkError

Raised when a network request times out.

url: The URL that timed out

timeout: The timeout value in seconds

__init__(message: str, url: str | None = None, timeout: float | None = None) → None[source]

exception nautical.exceptions.CacheError[source]

Bases: NauticalError

Base exception for cache-related errors.

exception nautical.exceptions.CacheNotFoundError(message: str, cache_path: str | None = None)[source]

Bases: CacheError, FileNotFoundError

Raised when a cache file cannot be found.

This exception inherits from FileNotFoundError for backward compatibility.

cache_path: The path to the cache file that was not found

__init__(message: str, cache_path: str | None = None) → None[source]

exception nautical.exceptions.CacheWriteError(message: str, cache_path: str | None = None, original_error: Exception | None = None)[source]

Bases: CacheError, OSError

Raised when a cache file cannot be written.

cache_path: The path to the cache file

original_error: The underlying exception

__init__(message: str, cache_path: str | None = None, original_error: Exception | None = None) → None[source]

exception nautical.exceptions.CacheReadError(message: str, cache_path: str | None = None, original_error: Exception | None = None)[source]

Bases: CacheError, OSError

Raised when a cache file cannot be read or parsed.

cache_path: The path to the cache file

original_error: The underlying exception

__init__(message: str, cache_path: str | None = None, original_error: Exception | None = None) → None[source]

exception nautical.exceptions.LocationError[source]

Bases: NauticalError

Base exception for location and coordinate errors.

exception nautical.exceptions.InvalidCoordinatesError(message: str, coordinates: str | tuple | None = None)[source]

Bases: LocationError, ValueError

Raised when coordinates are malformed or invalid.

This exception inherits from ValueError for backward compatibility.

coordinates: The invalid coordinate string or tuple

__init__(message: str, coordinates: str | tuple | None = None) → None[source]

exception nautical.exceptions.OutOfBoundsError(message: str, latitude: float | None = None, longitude: float | None = None, value: float | None = None, bounds: tuple[float, float] | None = None)[source]

Bases: LocationError, ValueError

Raised when coordinates are outside valid ranges.

Valid ranges:

Latitude: -90 to +90 degrees
Longitude: -180 to +180 degrees

latitude: The latitude value (if applicable)

longitude: The longitude value (if applicable)

value: The out-of-bounds value

bounds: The valid bounds as a tuple (min, max)

__init__(message: str, latitude: float | None = None, longitude: float | None = None, value: float | None = None, bounds: tuple[float, float] | None = None) → None[source]

exception nautical.exceptions.DistanceCalculationError(message: str, point1: object | None = None, point2: object | None = None, original_error: Exception | None = None)[source]

Bases: LocationError

Raised when distance calculation fails.

This typically occurs in Haversine distance calculations when invalid coordinates are provided.

point1: The first point

point2: The second point

original_error: The underlying exception

__init__(message: str, point1: object | None = None, point2: object | None = None, original_error: Exception | None = None) → None[source]

nautical.release module

Module contents

class nautical.Buoy(station: str, description: str | None = None, location: Point | None = None)[source]

Bases: object

__init__(station: str, description: str | None = None, location: Point | None = None) → None[source]

Parameters:

station – ID of the station
description – snippet of information to describe this station
location – nautical.location.point.Point [optional]

property location: Point | None

Location Property

Returns:: Copy of the location (Point)

property data: BuoyData | None

Copy of present Property. This is an expansion function for use when the past was deprecated.

Returns:: Copy of the present data stored in this instance

property present: BuoyData | None

Present Property, the present data stored in this instance. This is the most recent set of buoy data that was retrieved.

Returns:: Copy of the present data stored in this instance

property past: list[BuoyData]

Past Property.

Returns:: all past instances of Buoy Data objects stored in this instance.

__str__() → str[source]

If the location of this buoy is known return the location and the name, otherwise just return the name

Returns:: string representation of this Buoy

__eq__(other: object) → bool[source]

The stations are considered equal if their station ID is the same as the station IDs are meant to be unique. The special case is SHIP.

Parameters:: other – Buoy object to compare to this instance.
Returns:: True when the two objects are the same

__ne__(other: object) → bool[source]

See __eq__ for more information.

Returns:: The opposite of __eq__ (==)

__hash__() → int[source]

The reason behind a private station and description is that they are used for the hash function. The hash shouldn’t be able to change during execution.

Returns:: hash of the station combined with the hash of the description.

to_json() → dict[source]: Create a json dictionary representation of this instance

static from_json(json_dict: dict) → Buoy[source]: Return a Buoy object created from a json dictionary

from_dict(buoy_dict: dict) → None[source]: Fill this instance from a dictionary

class nautical.BuoyData[source]

Bases: object

Class to contain all information included in a NOAA data point for a buoy. A buoy can also include weather stations.

__init__() → None[source]

year

mm

dd

time

property epoch_time: int

Epoch time property. Converts the nautical time to the epoch time. The function assumes that the data is in UTC time.

Returns:: Seconds since the epoch in UTC, 0 on failure

__contains__(item: str) → bool[source]: Returns True when the value exists and is set

__iter__() → Iterator[tuple[str, Any]][source]: Provide a user friendly mapping of variable names to values stored in this Buoy Data Object

to_json() → dict[source]: Return the object as a json dict

static from_json(json_data: dict) → BuoyData[source]: Fill an instance from the json_data.

from_dict(buoy_data_dict: dict[str, Any]) → None[source]

Fill this object from the data stored in a dictionary where the key should match a slot or object variable

Parameters:: buoy_data_dict – Dictionary containing the data about this buoy

set(key: str, value: Any) → None[source]

Set a key, value pair. This function is intended to replace __setattr__ for simplcity. The function will also attempt to convert the noaa time to a formatted time that is readable.

Parameters:

key – the internal variable name
value – the value we wish to set the variable to

wdir

wspd

gst

mwd

wspd10m

wspd20m

wvht

dpd

apd

wwh

wwp

wwd

swh

swp

swd

pres

ptdy

atmp

wtmp

dewp

otmp

chill

heat

sal

ph

o2pct

o2ppm

depth

nmi

vis

tide

steepness

clcon

turb

cond

srad1

swrad

lwrad

class nautical.Source(name: str, description: str | None = None)[source]

Bases: object

The source is a grouping or categorization of buoy sources.

__init__(name: str, description: str | None = None) → None[source]

Parameters:

name – Name of the data source or grouping of data
description – Description tag of the data source

__len__() → int[source]: Return the number of buoys in this source

__copy__() → Source[source]: Override the copy function to only keep specific values. Notice that the buoys are not kept

__deepcopy__(memo: dict) → Source[source]: Override the deepcopy for this instance to include all private variables

__str__() → str[source]

String representation of this instance

Returns:: string representation of the source

__contains__(item: Buoy | int | str) → bool[source]

Determine if the item buoy exists in our dictionary. When item is a Buoy, check if the hash of the item is in the dict. when item is an int, assume this is the hash and check for it in the dict. When item is a str, assume this is the station name check if its in the dict.

Parameters:: item – should be a Buoy, String or int
Returns:: True when the item is found in this instance.

__iter__() → Iterator[Buoy][source]: Override iterate to provide the user with the buoys in this instance. Yield the Buoy objects in this instance.

__eq__(other: object) → bool[source]

Determine if this instance is the same as the other source

Returns:: True if name and description match

__ne__(other: object) → bool[source]

See __eq__ for more information

Returns:: True if the name or description do not match

property buoys: dict[int, Buoy]

Buoys Property for this instance

Returns:: Copy of the current set of buoys contained in this instance

add_buoy(buoy: Buoy) → bool[source]

Add a buoy to this instance

Note

Buoy names are case sensitive to ensure they are unique

Parameters:: buoy – buoy to be added to the list of buoys.
Returns:: True if the buoy was added to the list of buoys

get_buoy(station: str) → Buoy | None[source]

Get a buoy where the station matches the station of the Buoy

Note

Buoy names are case sensitive to ensure they are unique

Parameters:: station – name of the buoy station
Returns:: Buoy with a matching station, None if one was not found.

to_json() → dict[source]: Convert this instance to a json dictionary

static from_json(json_dict: dict) → Source[source]: Create/Fill/Return an instance from a json dictionary

from_dict(source_dict: dict) → None[source]: Fill in instance from a dictionary

class nautical.SourceType(value)[source]

Bases: Enum

An enumeration.

ALL = 0

INTERNATIONAL_PARTNERS = 1

IOOS_PARTNERS = 2

MARINE_METAR = 3

NDBC_METEOROLOGICAL_OCEAN = 4

NERRS = 5

NOS_CO_OPS = 6

SHIPS = 7

TAO = 8

TSUNAMI = 9

classmethod as_strings(source_type: SourceType) → str | list[str] | None[source]

Get the string value based on the type of source

Parameters:: source_type – Type of source from the enumeration
Returns:: List of strings that match the source type

class nautical.Point(lat: float = 0.0, lon: float = 0.0, alt: float = 0.0)[source]

Bases: object

A 3D point containing latitude, longitude and altitude coordinates.

__init__(lat: float = 0.0, lon: float = 0.0, alt: float = 0.0) → None[source]: The latitude, longitude, and altitude are supplied to the base class as the x, y, z parameters respectively.

property latitude: float: Latitude Property (degrees) :return: latitude (degrees)

property longitude: float: Longitude Property (degrees) :return: longitude (degrees)

property altitude: float: Altitude Property (meters) :return: altitude (meters)

property x: float

property y: float

property z: float

as_tuple() → tuple[float, float][source]

Get the values of the object as a simple tuple. The lat and lon are used but not the altitude. The altitude is omitted for use with haverine.

Returns:: Tuple of lat, lon

__str__() → str[source]

Python version of the to string function. Turn this object into a string

Returns:: string representation of this object

to_json() → dict[str, float][source]: Convert the instance to a json dictionary

static from_json(json_dict: dict[str, float]) → Point[source]: Fill the instance from a json dictionary

from_dict(point_dict: dict[str, float]) → None[source]: Fill the instance from a json dictionary

distance(other: Point, units: DistanceUnits = DistanceUnits.METERS) → float[source]

Get the distance using the Haversine function. The function will determine the distance between this instance and another Point.

Parameters:

other – The other Point
units – Units used for measurement

Returns:

Distance between the points in units specified

in_range(other: Point, distance: float, units: DistanceUnits = DistanceUnits.METERS) → bool[source]

Deteremine if the points are within a specific distance of eachother.

Parameters:

other – The other Point
distance – Max distance between the points
units – Units used for measurement

Returns:

True when points are within the specified distance

static parse(data: str) → Point[source]

Parse the string containing lon, lat, alt [optional] values respectively.

Parameters:: data – A string containing lon, lat, altitude.
Returns:: instance of Point on success, None on failure

static parse_noaa_kml_format(data: str) → Point[source]: Parse the string containing lon, lat, alt [optional] values respectively. See Point.parse for implementation and notes.

nautical.create_buoy(buoy: str) → Buoy | None[source]

Provide a full workup for a specific buoy. If the buoy is None or it cannot be found then the data returned will be considered invalid as None

Parameters:: buoy – id of the buoy to do a workup on
Returns:: BuoyWorkup if successful else None

nautical.fill_buoy(buoy: Buoy) → None[source]

Pass in a Buoy object that needs to be filled in with the current data. The buoy object will have the validity set if the results were successful

Parameters:: buoy – nautical.noaa.buoy.Buoy object

nautical.get_buoy_sources(source_types: SourceType | list[SourceType] = SourceType.ALL) → dict[str, Source][source]

NOAA is kind enough to provide all of names, ids, and other information about ALL of their known buoys in a kml document hosted at the link provided (https://www.ndbc.noaa.gov/kml/marineobs_by_pgm.kml). Read through this document and parse the buoy information to determine their id and location. The ID can be used to provide to get_noaa_forecast_url(). Then we can find even more information about the buoys.

Returns:: dictionary all source names mapped to their respective source.