| Name | pyais JSON |
| Version |
2.8.2
JSON |
| download |
| home_page | None |
| Summary | AIS message decoding |
| upload_time | 2024-11-11 11:42:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2019 M0r13n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
ais
ship
decoding
nmea
maritime
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
bitarray
attrs
flake8
coverage
mypy
pytest
pytest-cov
twine
wheel
sphinx
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="docs/logo.png" alt="Logo" width="80" height="80">
<h3 align="center">pyais</h3>
<p align="center">
AIS message encoding and decoding. 100% pure Python.
<br />
[](https://pypi.org/project/pyais/)
[](https://github.com/M0r13n/pyais/blob/master/LICENSE)
[](https://codecov.io/gh/M0r13n/pyais)
[](https://pypi.org/project/pyais/)
[](https://pyais.readthedocs.io/en/latest/?badge=latest)
</p>
</div>
---
Supports AIVDM/AIVDO messages. Supports single messages, files and
TCP/UDP sockets. This library has been used and tested extensively in representative real-world scenarios. This includes tests with live feeds from [Spire](https://spire.com/maritime/), the [Norwegian Coastal Administration](https://kystverket.no/en/navigation-and-monitoring/ais/access-to-ais-data/) and others. I test each major release against a selection of public and non-public data sources to ensure the broadest possible compatibility.
You can find the full documentation on [readthedocs](https://pyais.readthedocs.io/en/latest/).
Binary releases (Debian packages) are provided by the [pyais-debian](https://github.com/M0r13n/pyais-debian) starting with version **v2.5.6**. They are downloadable under the [Releases](https://github.com/M0r13n/pyais/releases) page.
# Acknowledgements
This project is a grateful recipient of
the [free Jetbrains Open Source sponsorship](https://www.jetbrains.com/?from=pyais). Thank you. 🙇
# General
AIS (Automatic Identification System) is a communication system that allows ships to automatically exchange information such as vessel identification, position, course, and speed. This information is transmitted via VHF radio and can be received by other ships and coastal stations, allowing them to accurately determine the location and movement of nearby vessels. AIS is often used for collision avoidance, traffic management, and search and rescue operations. AIS messages are often transmitted via NMEA 0183.
NMEA (National Marine Electronics Association) is an organization that develops and maintains standards for the interface of marine electronic equipment. NMEA 0183 is a standard for communicating marine instrument data between equipment on a boat. It defines the electrical interface and data protocol for sending data between marine instruments such as GPS, sonar, and autopilot.
Here is an example of an AIS sentence:
`!AIVDM,1,1,,B,15MwkT1P37G?fl0EJbR0OwT0@MS,0*4E`
This AIS sentence is known as a "Position Report" message and is used to transmit information about a vessel's position, course, and speed. AIS messages are transmitted in digital format and consist of a series of comma-separated fields that contain different types of data. Here is a breakdown of each field in this particular sentence:
- **!AIVDM**: This field indicates that the sentence is an AIS message in the "VDM" (VDO Message) format.
- **1,1**: These fields indicate the total number of sentences in the message and the current sentence number, respectively. In this case, the message consists of a single sentence.
- : This field is left blank. This field can contain the sequence number.
- **B**: This field indicates the communication channel being used to transmit the message. In this case, the channel is "B".
- **15MwkT1P37G?fl0EJbR0OwT0@MS**: This field contains the payload of the message, which is encoded using a variant of ASCII known as "Six-bit ASCII". The payload contains information such as the vessel's identification, position, course, and speed.
0\*4E: This field is a checksum that is used to verify the integrity of the sentence.
**pyais** is a Python modul to encode and decode AIS messages.
# Installation
The project is available at Pypi:
```shell
$ pip install pyais
```
# Usage
There are many examples in the [examples directory](https://github.com/M0r13n/pyais/tree/master/examples).
Decode a single part AIS message using `decode()`::
```py
from pyais import decode
decoded = decode(b"!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05")
print(decoded)
```
The `decode()` functions accepts a list of arguments: One argument for every part of a multipart message::
```py
from pyais import decode
parts = [
b"!AIVDM,2,1,4,A,55O0W7`00001L@gCWGA2uItLth@DqtL5@F22220j1h742t0Ht0000000,0*08",
b"!AIVDM,2,2,4,A,000000000000000,2*20",
]
# Decode a multipart message using decode
decoded = decode(*parts)
print(decoded)
```
Also the `decode()` function accepts either strings or bytes::
```py
from pyais import decode
decoded_b = decode(b"!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05")
decoded_s = decode("!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05")
assert decoded_b == decoded_s
```
Decode the message into a dictionary::
```py
from pyais import decode
decoded = decode(b"!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05")
as_dict = decoded.asdict()
print(as_dict)
```
Read a file::
```py
from pyais.stream import FileReaderStream
filename = "sample.ais"
with FileReaderStream(filename) as stream:
for msg in stream:
decoded = msg.decode()
print(decoded)
```
Decode a stream of messages (e.g. a list or generator)::
```py
from pyais import IterMessages
fake_stream = [
b"!AIVDM,1,1,,A,13HOI:0P0000VOHLCnHQKwvL05Ip,0*23",
b"!AIVDM,1,1,,A,133sVfPP00PD>hRMDH@jNOvN20S8,0*7F",
b"!AIVDM,1,1,,B,100h00PP0@PHFV`Mg5gTH?vNPUIp,0*3B",
b"!AIVDM,1,1,,B,13eaJF0P00Qd388Eew6aagvH85Ip,0*45",
b"!AIVDM,1,1,,A,14eGrSPP00ncMJTO5C6aBwvP2D0?,0*7A",
b"!AIVDM,1,1,,A,15MrVH0000KH<:V:NtBLoqFP2H9:,0*2F",
]
for msg in IterMessages(fake_stream):
print(msg.decode())
```
## Live feed
The [Norwegian Coastal Administration](https://kystverket.no/en/navigation-and-monitoring/ais/access-to-ais-data/) offers real-time AIS data.
This live feed can be accessed via TCP/IP without prior registration.
The AIS data is freely available under the [norwegian license for public data](https://data.norge.no/nlod/no/1.0):
Data can be read from a TCP/IP socket and is encoded according to IEC 62320-1:
- IP: 153.44.253.27
- Port: 5631
Refer to the [examples/live_stream.py](./examples/live_stream.py) for a practical example on how to read & decode AIS data from a TCP/IP socket.
This is useful for debugging or for getting used to pyais.
## Encode
It is also possible to encode messages.
| :exclamation: Every message needs at least a single keyword argument: `mmsi`. All other fields have most likely default values. |
| ------------------------------------------------------------------------------------------------------------------------------- |
### Encode data using a dictionary
You can pass a dict that has a set of key-value pairs:
- use `from pyais.encode import encode_dict` to import `encode_dict` method
- it takes a dictionary of data and some NMEA specific kwargs and returns the NMEA 0183 encoded AIS sentence.
- only keys known to each message are considered
- other keys are simply omitted
- you can get list of available keys by looking at pyais/encode.py
- you can also call `MessageType1.fields()` to get a list of fields programmatically for each message
- every message needs at least two keyword arguments:
- `mmsi` the MMSI number to encode
- `type` or `msg_type` the type of the message to encode (1-27)
**NOTE:**
This method takes care of splitting large payloads (larger than 60 characters)
into multiple sentences. With a total of 80 maximum chars excluding end of line per sentence, and 20 chars head + tail
in the nmea 0183 carrier protocol, 60 chars remain for the actual payload. Therefore, it returns a list of messages.
```py
from pyais.encode import encode_dict
data = {
'course': 219.3,
'lat': 37.802,
'lon': -122.341,
'mmsi': '366053209',
'type': 1,
}
# This will create a type 1 message for the MMSI 366053209 with lat, lon and course values specified above
encoded = encode_dict(data, radio_channel="B", talker_id="AIVDM")[0]
```
### Create a message directly
It is also possible to create messages directly and pass them to `encode_payload`.
```py
from pyais.messages import MessageType5
from pyais.encode import encode_msg
payload = MessageType5.create(mmsi="123", shipname="Titanic", callsign="TITANIC", destination="New York")
encoded = encode_msg(payload)
print(encoded)
```
# Under the hood
```mermaid
graph LR
raw -->|"!AIVDM,1,1,,B,6B?n;be,2*4A"| nmea
nmea[NMEASentence] -->|parse NMEA sentence layer| ais[AISSentence]
ais -->|decode| final[AISMessage]
```
Decoding each AIS message is a three step process.
At first, the NMEA 0183 physical protocol layer is parsed. The NMEA layer is the outer protocol layer that is used by **many different** sentences/protocols for data transmission. Just like Ethernet can be used as a data link protocol to transfer data between nodes, the NMEA protocol can be used to transmit data between maritime equipment.
After the raw message was parsed into a `NMEASentence`, the inner protocol layer is parsed. While there are **tons** of different inner protocols that build upon NMEA, **pyais** currently only supports AIS sentences. Every `AISSentence` holds basic information about the AIS message like:
- the AIS message ID
- the number of fill bits required for ASCII6 encoding
- the fragment count and fragment number
- the actual AIS payload
- the sequence number
Finally, the AIS payload is decoded based on the AIS ID. There are 27 different types of top level messages that are identified by their AIS ID.
# Tag block
Some messages may look strange at first. Typical AIS messages look roughly like this:
```txt
!AIVDM,1,1,,A,16:=?;0P00`SstvFnFbeGH6L088h,0*44
!AIVDM,1,1,,A,16`l:v8P0W8Vw>fDVB0t8OvJ0H;9,0*0A
!AIVDM,1,1,,A,169a:nP01g`hm4pB7:E0;@0L088i,0*5E
```
But sometimes such messages look something like this:
```
\s:2573135,c:1671620143*0B\!AIVDM,1,1,,A,16:=?;0P00`SstvFnFbeGH6L088h,0*44
\s:2573238,c:1671620143*0B\!AIVDM,1,1,,A,16`l:v8P0W8Vw>fDVB0t8OvJ0H;9,0*0A
\s:2573243,c:1671620143*0B\!AIVDM,1,1,,A,169a:nP01g`hm4pB7:E0;@0L088i,0*5E
```
These three messages are the same messages as above - only with a prefix, the **so called tag block.**
Tag blocks are essential key-value pairs that are wrapped between `\`s.
Every valid NMEA sentence may have **one of the these tag blocks**.
Tag blocks are used to hold extra information and somewhat similar to [Gatehouse messages](#gatehouse-wrappers).
A **tag block** consists of any number of comma-separated key-value pairs, followed by a checksum:
- `s:2573135,c:1671620143*0B` -> `s:2573135` & `c:1671620143` & `0*B`
The checksum is the same as for all NMEA messages.
Regarding the key value pairs:
- each key is a single letter
- each letter represents a field:
- **c**: Receiver timestamp in Unix epoch (e.g. `1671620143`)
- **d**: Destination station (e.g. `FooBar`)
- **n**: Line count (e.g. `123`)
- **r**: Relative time
- **s**: Source station (e.g. `APIDSSRC1`)
- **t**: Text (e.g.g `Hello World!`)
Some things to keep in mind when working with **tag blocks** and **pyais**:
- tag blocks are optional (a message may or may not have a tag block)
- tag blocks are lazily decoded by pyais to save resources (need to call `tb.init()`)
- only some fields are supported by pyais (c,d,n,r,s,t)
- unknown fields are simply omitted
## How to work with tag blocks
```py
from pyais.stream import IterMessages
text = """
\s:2573135,c:1671620143*0B\!AIVDM,1,1,,A,16:=?;0P00`SstvFnFbeGH6L088h,0*44
\s:2573238,c:1671620143*0B\!AIVDM,1,1,,A,16`l:v8P0W8Vw>fDVB0t8OvJ0H;9,0*0A
\s:2573243,c:1671620143*0B\!AIVDM,1,1,,A,169a:nP01g`hm4pB7:E0;@0L088i,0*5E
"""
messages = [line.encode() for line in text.split() if line]
with IterMessages(messages) as s:
for msg in s:
if msg.tag_block is not None:
# Not every message has a tag block
# Therefore, check if the tag block is not None
# Also, it is required to call `.init()`, because tag blocks are lazily parsed
msg.tag_block.init()
# Print the tag block data as a dictionary
print(msg.tag_block.asdict())
print(msg.decode())
```
## Tag Block Queue (grouping)
Every class that implements the streaming API accepts an optional keyword argument `tbq`, which is set to `None` by default. When tbq is provided, it can be used as a queue for handling NMEA tag blocks. The queue's `get_nowait()` method allows you to retrieve a list of NMEASentence objects, but only when the entire group has been received (i.e., all sentences within the group are complete). It is important to note that this is rudimentary support for tag block groups, as pyais primarily focuses on processing AIS messages and abstracts away NMEA sentences from the user.
```py
with FileReaderStream('/path/to/file.nmea', tbq=TagBlockQueue()) as stream:
tbq = stream.tbq
for msg in stream:
try:
print(tbq.get_nowait())
except queue.Empty:
pass
```
# Gatehouse wrappers
Some AIS messages have so-called Gatehouse wrappers. These encapsulating messages contain extra information, such as time and checksums. Some readers also process these. See some more documentation [here](https://www.iala-aism.org/wiki/iwrap/index.php/GH_AIS_Message_Format).
As an example, see the following, which is followed by a regular `!AIVDM` message
```
$PGHP,1,2020,12,31,23,59,58,239,0,0,0,1,2C*5B
```
Such messages are parsed by **pyais** only when using any of the classes from **pyais.stream**.
e.g. `FileReaderStream` or `TCPStream`.
Such additional information can then be accessed by the `.wrapper_msg` of every `NMEASentence`. This attribute is `None` by default.
# Communication State
The ITU documentation provides details regarding the Time-division multiple access (TDMA) synchronization.
Such details include information used by the slot allocation algorithm (either SOTDMA or ITDMA) including their synchronization state.
Refer to [readthedocs](https://pyais.readthedocs.io/en/latest/messages.html#communication-state) for more information.
# Preprocessing
The `PreprocessorProtocol` is designed to provide flexibility in handling different message formats. By implementing this protocol, users can create custom preprocessors that transform input messages into the required NMEA0183 format before further processing.
## Definition
```py
import typing
class PreprocessorProtocol(typing.Protocol):
def process(self, line: bytes) -> bytes:
pass
```
where `process` is defined as:
```py
def process(self, line: bytes) -> bytes:
pass
```
Parameters:
line (bytes): The input line in bytes that needs to be processed.
Returns:
bytes: The processed line in bytes, conforming to the NMEA0183 format.
The `process` method is responsible for transforming the input bytes into a format that adheres to the NMEA0183 standard. This method must be implemented by any class that conforms to the `PreprocessorProtocol`.
The custom preprocessor implementing the PreprocessorProtocol can be passed as an optional keyword argument (default None) to any class that implements the streaming protocol, excluding `IterMessages()`.
See [the preprocess example](./examples/preprocess.py) for an example implementation.
# AIS Filters
The filtering system is built around a series of filter classes, each designed to filter messages based on specific criteria. Filters are chained together using the `FilterChain` class, which allows combining multiple filters into a single, sequential filtering process. The system is flexible, allowing for the easy addition or removal of filters from the chain.
### How It Works
1. **AIS Stream**: Messages are provided as a stream to the filters.
2. **Filter Application**: Each filter in the chain applies its criteria to the stream, passing the messages that meet the criteria to the next filter.
3. **Filter Chain**: The `FilterChain` class orchestrates the passing of messages through each filter, from the first to the last.
## Filters
### 1. AttributeFilter
- **Description**: Filters messages based on a user-defined function.
- **Usage**: Initialize with a function that takes an AIS message and returns `True` if the message should be kept.
### 2. NoneFilter
- **Description**: Filters out messages where specified attributes are `None`.
- **Usage**: Initialize with the names of attributes that should not be `None` in the messages.
### 3. MessageTypeFilter
- **Description**: Filters messages based on their type.
- **Usage**: Initialize with message types to include.
### 4. DistanceFilter
- **Description**: Filters messages based on distance from a reference point.
- **Usage**: Initialize with a reference point (latitude and longitude) and a distance threshold in kilometers.
### 5. GridFilter
- **Description**: Filters messages based on whether they fall within a specified geographical grid.
- **Usage**: Initialize with the boundaries of the grid (minimum and maximum latitude and longitude).
## Utility Functions
### 1. Haversine
- **Description**: Calculates the great circle distance between two points on the Earth.
- **Parameters**: Takes two tuples representing the latitude and longitude of each point.
- **Returns**: Distance between the points in kilometers.
### 2. Is In Grid
- **Description**: Checks if a point is within a defined geographical grid.
- **Parameters**: Latitude and longitude of the point and the boundaries of the grid.
- **Returns**: `True` if the point is within the grid, `False` otherwise.
## FilterChain
- **Description**: Chains multiple filters together into a single filtering process.
- **Usage**: Initialize with a list of filters to be applied in order. The chain can be used to filter a stream of AIS messages.
## Example Usage
```python
from pyais import decode, TCPConnection
# ... (importing necessary classes)
# Define and initialize filters
attribute_filter = AttributeFilter(lambda x: not hasattr(x, 'turn') or x.turn == -128.0)
none_filter = NoneFilter('lon', 'lat', 'mmsi2')
message_type_filter = MessageTypeFilter(1, 2, 3)
distance_filter = DistanceFilter((51.900, 5.320), distance_km=1000)
grid_filter = GridFilter(lat_min=50, lon_min=0, lat_max=52, lon_max=5)
# Create a filter chain
chain = FilterChain([
attribute_filter,
none_filter,
message_type_filter,
distance_filter,
grid_filter,
])
# Decode AIS data and filter
stream = TCPConnection(...)
filtered_data = list(chain.filter(stream))
for msg in filtered_data:
print(msg.lat, msg.lon)
```
# AIS tracker
**pyais** comes with the the ability to collect and maintain the state of individual vessels over time.
This is necessary because several messages can give different information about a ship.
In addition, the data changes constantly (e.g. position, speed and course).
Thus the information split across multiple different AIS messages needs to be collected, consolidated and aggregated as a single track.
This functionality is handled by the `AISTracker` class.
**NOTE:** Each track (or vessel) is solely identified by its MMSI.
```py
import pathlib
from pyais import AISTracker
from pyais.stream import FileReaderStream
filename = pathlib.Path(__file__).parent.joinpath('sample.ais')
with FileReaderStream(str(filename)) as stream:
with AISTracker() as tracker:
for msg in stream:
tracker.update(msg)
latest_tracks = tracker.n_latest_tracks(10)
# Get the latest 10 tracks
print('latest 10 tracks', ','.join(str(t.mmsi) for t in latest_tracks))
# Get a specific track
print(tracker.get_track(249191000))
```
Unlike most other trackers, `AISTracker` handles out of order reception of messages.
This means that it is possible to pass messages to update() whose timestamp is
older that of the message before. The latter is useful when working with multiple stations
and/or different kinds of metadata.
But this comes with a performance penalty. In order to cleanup expired tracks and/or to get the latest N tracks the tracks need to be sorted after their timestamp. Thus, `cleanup()` and `n_latest_tracks()` have a complexity of `O(N * log(N))`. Depending on the number of messages in your stream this may or may not be good enough.
If you know that your messages in your stream are ordered after their timestamp and/or you never pass a custom timestamp to `update()`, you <mark>should set the `stream_is_ordered=True` flag when creating a new `AISTracker` instance</mark>. If this flag is set `AISTracker` internally stores the tracks in order. Thus, `cleanup()` and `n_latest_tracks()` have a complexity of `O(k)`.
## Callbacks
It is possible to register event listeners as callbacks,
so that you are is instantly notified whenever a track is created, updated, or deleted.
```py
import pyais
from pyais.tracker import AISTrackEvent
host = '153.44.253.27'
port = 5631
def handle_create(track):
# called every time an AISTrack is created
print('create', track.mmsi)
def handle_update(track):
# called every time an AISTrack is updated
print('update', track.mmsi)
def handle_delete(track):
# called every time an AISTrack is deleted (pruned)
print('delete', track.mmsi)
with pyais.AISTracker() as tracker:
tracker.register_callback(AISTrackEvent.CREATED, handle_create)
tracker.register_callback(AISTrackEvent.UPDATED, handle_update)
tracker.register_callback(AISTrackEvent.DELETED, handle_delete)
for msg in pyais.TCPConnection(host, port=port):
tracker.update(msg)
latest_tracks = tracker.n_latest_tracks(10)
```
# Performance Considerations
You may refer to
the [Code Review Stack Exchange question](https://codereview.stackexchange.com/questions/230258/decoding-of-binary-data-ais-from-socket)
. After a some research I decided to use the bitarray module as foundation. This module uses a C extension under the
hood and has a nice user interface in Python. Performance is also great. Decoding
this [sample](https://www.aishub.net/ais-dispatcher) with roughly 85k messages takes **less than 6 seconds** on my
machine. For comparison, the C++ based [libais module](https://github.com/schwehr/libais) parses the same file in \~ 2
seconds.
# Disclaimer
This module is a private project of mine and does not claim to be complete. I try to improve and extend it, but there
may be bugs. If you find such a bug feel free to submit an issue or even better create a pull-request. :-)
# Coverage
Currently, this module is able to decode most message types. There are only a few exceptions. These are messages that
only occur in very rare cases and that you will probably never observe. The module was able to completely decode a 4
hour stream with real-time data from San Francisco Bay Area without any errors or problems. If you find a bug or missing
feature, please create an issue.
# Known Issues
During installation, you may encounter problems due to missing header files. The error looks like this:
```sh
...
bitarray/_bitarray.c:13:10: fatal error: Python.h: No such file or directory
13 | #include "Python.h"
| ^~~~~~~~~~
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
...
```
In order to solve this issue, you need to install header files and static libraries for python dev:
```sh
$ sudo apt install python3-dev
```
# For developers
After you cloned the repo head into the `pyais` base directory.
Then install all dependencies:
```sh
$ pip install .[test]
```
Make sure that all tests pass and that there aren't any issues:
```sh
$ make test
```
Now you are ready to start developing on the project! Don't forget to add tests for every new change or feature!
# Docker
Use Docker to run your application inside a container. At first you need to build the image locally:
`docker build . -t pyais`
Afterwards, run the container (bash):
`docker run -it --rm pyais /bin/bash`
You can then run the examples inside the container:
`python ./examples/live_stream.py`
# Funfacts
## Python3.11 is faster
With Python3.11 significant improvements to the CPython Runtime were made:
- [What's new with Python 3.11](https://docs.python.org/3/whatsnew/3.11.html)
- [Faster CPython](https://docs.python.org/3/whatsnew/3.11.html#whatsnew311-faster-cpython)
Some results from the internal [performance test](https://github.com/M0r13n/pyais/blob/master/tests/test_file_stream.py#L155):
**3.10:**
`Decoding 82758 messages took: 3.233757972717285`
**3.11:**
`Decoding 82758 messages took: 2.5866270065307617`
Raw data
{
"_id": null,
"home_page": null,
"name": "pyais",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Leon Morten Richter <misc@leonmortenrichter.de>",
"keywords": "AIS, ship, decoding, NMEA, maritime",
"author": null,
"author_email": "Leon Morten Richter <misc@leonmortenrichter.de>",
"download_url": "https://files.pythonhosted.org/packages/28/e9/f6a5849e60e137b5d494ba2757e928f24cedefb9b23fd085369d6725e7a0/pyais-2.8.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"docs/logo.png\" alt=\"Logo\" width=\"80\" height=\"80\">\n\n <h3 align=\"center\">pyais</h3>\n\n <p align=\"center\">\n AIS message encoding and decoding. 100% pure Python.\n <br />\n\n[](https://pypi.org/project/pyais/)\n[](https://github.com/M0r13n/pyais/blob/master/LICENSE)\n[](https://codecov.io/gh/M0r13n/pyais)\n[](https://pypi.org/project/pyais/)\n\n[](https://pyais.readthedocs.io/en/latest/?badge=latest)\n\n </p>\n</div>\n\n---\n\nSupports AIVDM/AIVDO messages. Supports single messages, files and\nTCP/UDP sockets. This library has been used and tested extensively in representative real-world scenarios. This includes tests with live feeds from [Spire](https://spire.com/maritime/), the [Norwegian Coastal Administration](https://kystverket.no/en/navigation-and-monitoring/ais/access-to-ais-data/) and others. I test each major release against a selection of public and non-public data sources to ensure the broadest possible compatibility.\n\nYou can find the full documentation on [readthedocs](https://pyais.readthedocs.io/en/latest/).\n\nBinary releases (Debian packages) are provided by the [pyais-debian](https://github.com/M0r13n/pyais-debian) starting with version **v2.5.6**. They are downloadable under the [Releases](https://github.com/M0r13n/pyais/releases) page.\n\n# Acknowledgements\n\n\n\nThis project is a grateful recipient of\nthe [free Jetbrains Open Source sponsorship](https://www.jetbrains.com/?from=pyais). Thank you. \ud83d\ude47\n\n# General\n\nAIS (Automatic Identification System) is a communication system that allows ships to automatically exchange information such as vessel identification, position, course, and speed. This information is transmitted via VHF radio and can be received by other ships and coastal stations, allowing them to accurately determine the location and movement of nearby vessels. AIS is often used for collision avoidance, traffic management, and search and rescue operations. AIS messages are often transmitted via NMEA 0183.\n\nNMEA (National Marine Electronics Association) is an organization that develops and maintains standards for the interface of marine electronic equipment. NMEA 0183 is a standard for communicating marine instrument data between equipment on a boat. It defines the electrical interface and data protocol for sending data between marine instruments such as GPS, sonar, and autopilot.\n\nHere is an example of an AIS sentence:\n\n`!AIVDM,1,1,,B,15MwkT1P37G?fl0EJbR0OwT0@MS,0*4E`\n\nThis AIS sentence is known as a \"Position Report\" message and is used to transmit information about a vessel's position, course, and speed. AIS messages are transmitted in digital format and consist of a series of comma-separated fields that contain different types of data. Here is a breakdown of each field in this particular sentence:\n\n- **!AIVDM**: This field indicates that the sentence is an AIS message in the \"VDM\" (VDO Message) format.\n- **1,1**: These fields indicate the total number of sentences in the message and the current sentence number, respectively. In this case, the message consists of a single sentence.\n- : This field is left blank. This field can contain the sequence number.\n- **B**: This field indicates the communication channel being used to transmit the message. In this case, the channel is \"B\".\n- **15MwkT1P37G?fl0EJbR0OwT0@MS**: This field contains the payload of the message, which is encoded using a variant of ASCII known as \"Six-bit ASCII\". The payload contains information such as the vessel's identification, position, course, and speed.\n 0\\*4E: This field is a checksum that is used to verify the integrity of the sentence.\n\n**pyais** is a Python modul to encode and decode AIS messages.\n\n# Installation\n\nThe project is available at Pypi:\n\n```shell\n$ pip install pyais\n```\n\n# Usage\n\nThere are many examples in the [examples directory](https://github.com/M0r13n/pyais/tree/master/examples).\n\nDecode a single part AIS message using `decode()`::\n\n```py\nfrom pyais import decode\n\ndecoded = decode(b\"!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05\")\nprint(decoded)\n```\n\nThe `decode()` functions accepts a list of arguments: One argument for every part of a multipart message::\n\n```py\nfrom pyais import decode\n\nparts = [\n b\"!AIVDM,2,1,4,A,55O0W7`00001L@gCWGA2uItLth@DqtL5@F22220j1h742t0Ht0000000,0*08\",\n b\"!AIVDM,2,2,4,A,000000000000000,2*20\",\n]\n\n# Decode a multipart message using decode\ndecoded = decode(*parts)\nprint(decoded)\n```\n\nAlso the `decode()` function accepts either strings or bytes::\n\n```py\nfrom pyais import decode\n\ndecoded_b = decode(b\"!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05\")\ndecoded_s = decode(\"!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05\")\nassert decoded_b == decoded_s\n```\n\nDecode the message into a dictionary::\n\n```py\nfrom pyais import decode\n\ndecoded = decode(b\"!AIVDM,1,1,,B,15NG6V0P01G?cFhE`R2IU?wn28R>,0*05\")\nas_dict = decoded.asdict()\nprint(as_dict)\n```\n\nRead a file::\n\n```py\nfrom pyais.stream import FileReaderStream\n\nfilename = \"sample.ais\"\n\nwith FileReaderStream(filename) as stream:\n for msg in stream:\n decoded = msg.decode()\n print(decoded)\n```\n\nDecode a stream of messages (e.g. a list or generator)::\n\n```py\nfrom pyais import IterMessages\n\nfake_stream = [\n b\"!AIVDM,1,1,,A,13HOI:0P0000VOHLCnHQKwvL05Ip,0*23\",\n b\"!AIVDM,1,1,,A,133sVfPP00PD>hRMDH@jNOvN20S8,0*7F\",\n b\"!AIVDM,1,1,,B,100h00PP0@PHFV`Mg5gTH?vNPUIp,0*3B\",\n b\"!AIVDM,1,1,,B,13eaJF0P00Qd388Eew6aagvH85Ip,0*45\",\n b\"!AIVDM,1,1,,A,14eGrSPP00ncMJTO5C6aBwvP2D0?,0*7A\",\n b\"!AIVDM,1,1,,A,15MrVH0000KH<:V:NtBLoqFP2H9:,0*2F\",\n]\nfor msg in IterMessages(fake_stream):\n print(msg.decode())\n```\n\n## Live feed\n\nThe [Norwegian Coastal Administration](https://kystverket.no/en/navigation-and-monitoring/ais/access-to-ais-data/) offers real-time AIS data.\nThis live feed can be accessed via TCP/IP without prior registration.\nThe AIS data is freely available under the [norwegian license for public data](https://data.norge.no/nlod/no/1.0):\n\nData can be read from a TCP/IP socket and is encoded according to IEC 62320-1:\n\n- IP: 153.44.253.27\n- Port: 5631\n\nRefer to the [examples/live_stream.py](./examples/live_stream.py) for a practical example on how to read & decode AIS data from a TCP/IP socket.\nThis is useful for debugging or for getting used to pyais.\n\n## Encode\n\nIt is also possible to encode messages.\n\n| :exclamation: Every message needs at least a single keyword argument: `mmsi`. All other fields have most likely default values. |\n| ------------------------------------------------------------------------------------------------------------------------------- |\n\n### Encode data using a dictionary\n\nYou can pass a dict that has a set of key-value pairs:\n\n- use `from pyais.encode import encode_dict` to import `encode_dict` method\n- it takes a dictionary of data and some NMEA specific kwargs and returns the NMEA 0183 encoded AIS sentence.\n- only keys known to each message are considered\n - other keys are simply omitted\n - you can get list of available keys by looking at pyais/encode.py\n - you can also call `MessageType1.fields()` to get a list of fields programmatically for each message\n- every message needs at least two keyword arguments:\n - `mmsi` the MMSI number to encode\n - `type` or `msg_type` the type of the message to encode (1-27)\n\n**NOTE:**\nThis method takes care of splitting large payloads (larger than 60 characters)\ninto multiple sentences. With a total of 80 maximum chars excluding end of line per sentence, and 20 chars head + tail\nin the nmea 0183 carrier protocol, 60 chars remain for the actual payload. Therefore, it returns a list of messages.\n\n```py\nfrom pyais.encode import encode_dict\n\ndata = {\n 'course': 219.3,\n 'lat': 37.802,\n 'lon': -122.341,\n 'mmsi': '366053209',\n 'type': 1,\n}\n# This will create a type 1 message for the MMSI 366053209 with lat, lon and course values specified above\nencoded = encode_dict(data, radio_channel=\"B\", talker_id=\"AIVDM\")[0]\n```\n\n### Create a message directly\n\nIt is also possible to create messages directly and pass them to `encode_payload`.\n\n```py\nfrom pyais.messages import MessageType5\nfrom pyais.encode import encode_msg\n\npayload = MessageType5.create(mmsi=\"123\", shipname=\"Titanic\", callsign=\"TITANIC\", destination=\"New York\")\nencoded = encode_msg(payload)\nprint(encoded)\n```\n\n# Under the hood\n\n```mermaid\ngraph LR\n raw -->|\"!AIVDM,1,1,,B,6B?n;be,2*4A\"| nmea\n nmea[NMEASentence] -->|parse NMEA sentence layer| ais[AISSentence]\n ais -->|decode| final[AISMessage]\n```\n\nDecoding each AIS message is a three step process.\n\nAt first, the NMEA 0183 physical protocol layer is parsed. The NMEA layer is the outer protocol layer that is used by **many different** sentences/protocols for data transmission. Just like Ethernet can be used as a data link protocol to transfer data between nodes, the NMEA protocol can be used to transmit data between maritime equipment.\n\nAfter the raw message was parsed into a `NMEASentence`, the inner protocol layer is parsed. While there are **tons** of different inner protocols that build upon NMEA, **pyais** currently only supports AIS sentences. Every `AISSentence` holds basic information about the AIS message like:\n\n- the AIS message ID\n- the number of fill bits required for ASCII6 encoding\n- the fragment count and fragment number\n- the actual AIS payload\n- the sequence number\n\nFinally, the AIS payload is decoded based on the AIS ID. There are 27 different types of top level messages that are identified by their AIS ID.\n\n# Tag block\n\nSome messages may look strange at first. Typical AIS messages look roughly like this:\n\n```txt\n!AIVDM,1,1,,A,16:=?;0P00`SstvFnFbeGH6L088h,0*44\n!AIVDM,1,1,,A,16`l:v8P0W8Vw>fDVB0t8OvJ0H;9,0*0A\n!AIVDM,1,1,,A,169a:nP01g`hm4pB7:E0;@0L088i,0*5E\n```\n\nBut sometimes such messages look something like this:\n\n```\n\\s:2573135,c:1671620143*0B\\!AIVDM,1,1,,A,16:=?;0P00`SstvFnFbeGH6L088h,0*44\n\\s:2573238,c:1671620143*0B\\!AIVDM,1,1,,A,16`l:v8P0W8Vw>fDVB0t8OvJ0H;9,0*0A\n\\s:2573243,c:1671620143*0B\\!AIVDM,1,1,,A,169a:nP01g`hm4pB7:E0;@0L088i,0*5E\n```\n\nThese three messages are the same messages as above - only with a prefix, the **so called tag block.**\nTag blocks are essential key-value pairs that are wrapped between `\\`s.\nEvery valid NMEA sentence may have **one of the these tag blocks**.\nTag blocks are used to hold extra information and somewhat similar to [Gatehouse messages](#gatehouse-wrappers).\n\nA **tag block** consists of any number of comma-separated key-value pairs, followed by a checksum:\n\n- `s:2573135,c:1671620143*0B` -> `s:2573135` & `c:1671620143` & `0*B`\n\nThe checksum is the same as for all NMEA messages.\nRegarding the key value pairs:\n\n- each key is a single letter\n- each letter represents a field:\n - **c**: Receiver timestamp in Unix epoch (e.g. `1671620143`)\n - **d**: Destination station (e.g. `FooBar`)\n - **n**: Line count (e.g. `123`)\n - **r**: Relative time\n - **s**: Source station (e.g. `APIDSSRC1`)\n - **t**: Text (e.g.g `Hello World!`)\n\nSome things to keep in mind when working with **tag blocks** and **pyais**:\n\n- tag blocks are optional (a message may or may not have a tag block)\n- tag blocks are lazily decoded by pyais to save resources (need to call `tb.init()`)\n- only some fields are supported by pyais (c,d,n,r,s,t)\n - unknown fields are simply omitted\n\n## How to work with tag blocks\n\n```py\nfrom pyais.stream import IterMessages\n\n\ntext = \"\"\"\n\\s:2573135,c:1671620143*0B\\!AIVDM,1,1,,A,16:=?;0P00`SstvFnFbeGH6L088h,0*44\n\\s:2573238,c:1671620143*0B\\!AIVDM,1,1,,A,16`l:v8P0W8Vw>fDVB0t8OvJ0H;9,0*0A\n\\s:2573243,c:1671620143*0B\\!AIVDM,1,1,,A,169a:nP01g`hm4pB7:E0;@0L088i,0*5E\n\"\"\"\n\nmessages = [line.encode() for line in text.split() if line]\n\nwith IterMessages(messages) as s:\n for msg in s:\n if msg.tag_block is not None:\n # Not every message has a tag block\n # Therefore, check if the tag block is not None\n # Also, it is required to call `.init()`, because tag blocks are lazily parsed\n msg.tag_block.init()\n # Print the tag block data as a dictionary\n print(msg.tag_block.asdict())\n print(msg.decode())\n```\n\n## Tag Block Queue (grouping)\n\nEvery class that implements the streaming API accepts an optional keyword argument `tbq`, which is set to `None` by default. When tbq is provided, it can be used as a queue for handling NMEA tag blocks. The queue's `get_nowait()` method allows you to retrieve a list of NMEASentence objects, but only when the entire group has been received (i.e., all sentences within the group are complete). It is important to note that this is rudimentary support for tag block groups, as pyais primarily focuses on processing AIS messages and abstracts away NMEA sentences from the user.\n\n```py\nwith FileReaderStream('/path/to/file.nmea', tbq=TagBlockQueue()) as stream:\n tbq = stream.tbq\n\n for msg in stream:\n try:\n print(tbq.get_nowait())\n except queue.Empty:\n pass\n```\n\n# Gatehouse wrappers\n\nSome AIS messages have so-called Gatehouse wrappers. These encapsulating messages contain extra information, such as time and checksums. Some readers also process these. See some more documentation [here](https://www.iala-aism.org/wiki/iwrap/index.php/GH_AIS_Message_Format).\n\nAs an example, see the following, which is followed by a regular `!AIVDM` message\n\n```\n$PGHP,1,2020,12,31,23,59,58,239,0,0,0,1,2C*5B\n```\n\nSuch messages are parsed by **pyais** only when using any of the classes from **pyais.stream**.\ne.g. `FileReaderStream` or `TCPStream`.\n\nSuch additional information can then be accessed by the `.wrapper_msg` of every `NMEASentence`. This attribute is `None` by default.\n\n# Communication State\n\nThe ITU documentation provides details regarding the Time-division multiple access (TDMA) synchronization.\n\nSuch details include information used by the slot allocation algorithm (either SOTDMA or ITDMA) including their synchronization state.\n\nRefer to [readthedocs](https://pyais.readthedocs.io/en/latest/messages.html#communication-state) for more information.\n\n# Preprocessing\n\nThe `PreprocessorProtocol` is designed to provide flexibility in handling different message formats. By implementing this protocol, users can create custom preprocessors that transform input messages into the required NMEA0183 format before further processing.\n\n## Definition\n\n```py\nimport typing\n\nclass PreprocessorProtocol(typing.Protocol):\n def process(self, line: bytes) -> bytes:\n pass\n```\n\nwhere `process` is defined as:\n\n```py\ndef process(self, line: bytes) -> bytes:\n pass\n```\n\nParameters:\nline (bytes): The input line in bytes that needs to be processed.\nReturns:\nbytes: The processed line in bytes, conforming to the NMEA0183 format.\n\nThe `process` method is responsible for transforming the input bytes into a format that adheres to the NMEA0183 standard. This method must be implemented by any class that conforms to the `PreprocessorProtocol`.\n\nThe custom preprocessor implementing the PreprocessorProtocol can be passed as an optional keyword argument (default None) to any class that implements the streaming protocol, excluding `IterMessages()`.\n\nSee [the preprocess example](./examples/preprocess.py) for an example implementation.\n\n# AIS Filters\n\nThe filtering system is built around a series of filter classes, each designed to filter messages based on specific criteria. Filters are chained together using the `FilterChain` class, which allows combining multiple filters into a single, sequential filtering process. The system is flexible, allowing for the easy addition or removal of filters from the chain.\n\n### How It Works\n\n1. **AIS Stream**: Messages are provided as a stream to the filters.\n2. **Filter Application**: Each filter in the chain applies its criteria to the stream, passing the messages that meet the criteria to the next filter.\n3. **Filter Chain**: The `FilterChain` class orchestrates the passing of messages through each filter, from the first to the last.\n\n## Filters\n\n### 1. AttributeFilter\n\n- **Description**: Filters messages based on a user-defined function.\n- **Usage**: Initialize with a function that takes an AIS message and returns `True` if the message should be kept.\n\n### 2. NoneFilter\n\n- **Description**: Filters out messages where specified attributes are `None`.\n- **Usage**: Initialize with the names of attributes that should not be `None` in the messages.\n\n### 3. MessageTypeFilter\n\n- **Description**: Filters messages based on their type.\n- **Usage**: Initialize with message types to include.\n\n### 4. DistanceFilter\n\n- **Description**: Filters messages based on distance from a reference point.\n- **Usage**: Initialize with a reference point (latitude and longitude) and a distance threshold in kilometers.\n\n### 5. GridFilter\n\n- **Description**: Filters messages based on whether they fall within a specified geographical grid.\n- **Usage**: Initialize with the boundaries of the grid (minimum and maximum latitude and longitude).\n\n## Utility Functions\n\n### 1. Haversine\n\n- **Description**: Calculates the great circle distance between two points on the Earth.\n- **Parameters**: Takes two tuples representing the latitude and longitude of each point.\n- **Returns**: Distance between the points in kilometers.\n\n### 2. Is In Grid\n\n- **Description**: Checks if a point is within a defined geographical grid.\n- **Parameters**: Latitude and longitude of the point and the boundaries of the grid.\n- **Returns**: `True` if the point is within the grid, `False` otherwise.\n\n## FilterChain\n\n- **Description**: Chains multiple filters together into a single filtering process.\n- **Usage**: Initialize with a list of filters to be applied in order. The chain can be used to filter a stream of AIS messages.\n\n## Example Usage\n\n```python\nfrom pyais import decode, TCPConnection\n# ... (importing necessary classes)\n\n# Define and initialize filters\nattribute_filter = AttributeFilter(lambda x: not hasattr(x, 'turn') or x.turn == -128.0)\nnone_filter = NoneFilter('lon', 'lat', 'mmsi2')\nmessage_type_filter = MessageTypeFilter(1, 2, 3)\ndistance_filter = DistanceFilter((51.900, 5.320), distance_km=1000)\ngrid_filter = GridFilter(lat_min=50, lon_min=0, lat_max=52, lon_max=5)\n\n# Create a filter chain\nchain = FilterChain([\n attribute_filter,\n none_filter,\n message_type_filter,\n distance_filter,\n grid_filter,\n])\n\n# Decode AIS data and filter\nstream = TCPConnection(...)\nfiltered_data = list(chain.filter(stream))\n\nfor msg in filtered_data:\n print(msg.lat, msg.lon)\n```\n\n# AIS tracker\n\n**pyais** comes with the the ability to collect and maintain the state of individual vessels over time.\nThis is necessary because several messages can give different information about a ship.\nIn addition, the data changes constantly (e.g. position, speed and course).\n\nThus the information split across multiple different AIS messages needs to be collected, consolidated and aggregated as a single track.\nThis functionality is handled by the `AISTracker` class.\n\n**NOTE:** Each track (or vessel) is solely identified by its MMSI.\n\n```py\nimport pathlib\n\nfrom pyais import AISTracker\nfrom pyais.stream import FileReaderStream\n\nfilename = pathlib.Path(__file__).parent.joinpath('sample.ais')\n\nwith FileReaderStream(str(filename)) as stream:\n with AISTracker() as tracker:\n for msg in stream:\n tracker.update(msg)\n latest_tracks = tracker.n_latest_tracks(10)\n\n# Get the latest 10 tracks\nprint('latest 10 tracks', ','.join(str(t.mmsi) for t in latest_tracks))\n\n# Get a specific track\nprint(tracker.get_track(249191000))\n```\n\nUnlike most other trackers, `AISTracker` handles out of order reception of messages.\nThis means that it is possible to pass messages to update() whose timestamp is\nolder that of the message before. The latter is useful when working with multiple stations\nand/or different kinds of metadata.\n\nBut this comes with a performance penalty. In order to cleanup expired tracks and/or to get the latest N tracks the tracks need to be sorted after their timestamp. Thus, `cleanup()` and `n_latest_tracks()` have a complexity of `O(N * log(N))`. Depending on the number of messages in your stream this may or may not be good enough.\n\nIf you know that your messages in your stream are ordered after their timestamp and/or you never pass a custom timestamp to `update()`, you <mark>should set the `stream_is_ordered=True` flag when creating a new `AISTracker` instance</mark>. If this flag is set `AISTracker` internally stores the tracks in order. Thus, `cleanup()` and `n_latest_tracks()` have a complexity of `O(k)`.\n\n## Callbacks\n\nIt is possible to register event listeners as callbacks,\nso that you are is instantly notified whenever a track is created, updated, or deleted.\n\n```py\nimport pyais\nfrom pyais.tracker import AISTrackEvent\n\nhost = '153.44.253.27'\nport = 5631\n\n\ndef handle_create(track):\n # called every time an AISTrack is created\n print('create', track.mmsi)\n\n\ndef handle_update(track):\n # called every time an AISTrack is updated\n print('update', track.mmsi)\n\n\ndef handle_delete(track):\n # called every time an AISTrack is deleted (pruned)\n print('delete', track.mmsi)\n\n\nwith pyais.AISTracker() as tracker:\n tracker.register_callback(AISTrackEvent.CREATED, handle_create)\n tracker.register_callback(AISTrackEvent.UPDATED, handle_update)\n tracker.register_callback(AISTrackEvent.DELETED, handle_delete)\n\n for msg in pyais.TCPConnection(host, port=port):\n tracker.update(msg)\n latest_tracks = tracker.n_latest_tracks(10)\n```\n\n# Performance Considerations\n\nYou may refer to\nthe [Code Review Stack Exchange question](https://codereview.stackexchange.com/questions/230258/decoding-of-binary-data-ais-from-socket)\n. After a some research I decided to use the bitarray module as foundation. This module uses a C extension under the\nhood and has a nice user interface in Python. Performance is also great. Decoding\nthis [sample](https://www.aishub.net/ais-dispatcher) with roughly 85k messages takes **less than 6 seconds** on my\nmachine. For comparison, the C++ based [libais module](https://github.com/schwehr/libais) parses the same file in \\~ 2\nseconds.\n\n# Disclaimer\n\nThis module is a private project of mine and does not claim to be complete. I try to improve and extend it, but there\nmay be bugs. If you find such a bug feel free to submit an issue or even better create a pull-request. :-)\n\n# Coverage\n\nCurrently, this module is able to decode most message types. There are only a few exceptions. These are messages that\nonly occur in very rare cases and that you will probably never observe. The module was able to completely decode a 4\nhour stream with real-time data from San Francisco Bay Area without any errors or problems. If you find a bug or missing\nfeature, please create an issue.\n\n# Known Issues\n\nDuring installation, you may encounter problems due to missing header files. The error looks like this:\n\n```sh\n...\n\n bitarray/_bitarray.c:13:10: fatal error: Python.h: No such file or directory\n 13 | #include \"Python.h\"\n | ^~~~~~~~~~\n compilation terminated.\n error: command 'x86_64-linux-gnu-gcc' failed with exit status 1\n\n...\n\n```\n\nIn order to solve this issue, you need to install header files and static libraries for python dev:\n\n```sh\n$ sudo apt install python3-dev\n```\n\n# For developers\n\nAfter you cloned the repo head into the `pyais` base directory.\n\nThen install all dependencies:\n\n```sh\n$ pip install .[test]\n```\n\nMake sure that all tests pass and that there aren't any issues:\n\n```sh\n$ make test\n```\n\nNow you are ready to start developing on the project! Don't forget to add tests for every new change or feature!\n\n# Docker\n\nUse Docker to run your application inside a container. At first you need to build the image locally:\n\n`docker build . -t pyais`\n\nAfterwards, run the container (bash):\n\n`docker run -it --rm pyais /bin/bash`\n\nYou can then run the examples inside the container:\n\n`python ./examples/live_stream.py`\n\n# Funfacts\n\n## Python3.11 is faster\n\nWith Python3.11 significant improvements to the CPython Runtime were made:\n\n- [What's new with Python 3.11](https://docs.python.org/3/whatsnew/3.11.html)\n- [Faster CPython](https://docs.python.org/3/whatsnew/3.11.html#whatsnew311-faster-cpython)\n\nSome results from the internal [performance test](https://github.com/M0r13n/pyais/blob/master/tests/test_file_stream.py#L155):\n\n**3.10:**\n`Decoding 82758 messages took: 3.233757972717285`\n\n**3.11:**\n`Decoding 82758 messages took: 2.5866270065307617`\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2019 M0r13n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "AIS message decoding",
"version": "2.8.2",
"project_urls": {
"Homepage": "https://github.com/M0r13n/pyais",
"Source": "https://github.com/M0r13n/pyais"
},
"split_keywords": [
"ais",
" ship",
" decoding",
" nmea",
" maritime"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b0c03c870dd4480f87212266a4a951e2f0756a77dfb6bd41b28b7ae2b808a55",
"md5": "81f8770573ef2ecc63f576b70a2c120b",
"sha256": "1ef3ce413b797fbe771aa3712915d07366d550f8189f1b481c87cf03d9c2bf30"
},
"downloads": -1,
"filename": "pyais-2.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81f8770573ef2ecc63f576b70a2c120b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 52531,
"upload_time": "2024-11-11T11:42:41",
"upload_time_iso_8601": "2024-11-11T11:42:41.257040Z",
"url": "https://files.pythonhosted.org/packages/2b/0c/03c870dd4480f87212266a4a951e2f0756a77dfb6bd41b28b7ae2b808a55/pyais-2.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28e9f6a5849e60e137b5d494ba2757e928f24cedefb9b23fd085369d6725e7a0",
"md5": "7b9c0b649f77c847cdae2e8a9954745a",
"sha256": "176aed4ca164e7415c090036df01524a85c3536dcc7adf5e3e30a5c094f829f1"
},
"downloads": -1,
"filename": "pyais-2.8.2.tar.gz",
"has_sig": false,
"md5_digest": "7b9c0b649f77c847cdae2e8a9954745a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 95859,
"upload_time": "2024-11-11T11:42:43",
"upload_time_iso_8601": "2024-11-11T11:42:43.184512Z",
"url": "https://files.pythonhosted.org/packages/28/e9/f6a5849e60e137b5d494ba2757e928f24cedefb9b23fd085369d6725e7a0/pyais-2.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-11 11:42:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "M0r13n",
"github_project": "pyais",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "bitarray",
"specs": []
},
{
"name": "attrs",
"specs": []
},
{
"name": "flake8",
"specs": []
},
{
"name": "coverage",
"specs": []
},
{
"name": "mypy",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "twine",
"specs": []
},
{
"name": "wheel",
"specs": []
},
{
"name": "sphinx",
"specs": []
}
],
"lcname": "pyais"
}
