orion-nais 0.2.0

A client for the NAIS API from FThe Norwegian Coastal Administration

Orion-NAIS

Table of Contents

1. About The Project
   • Why the nanme Orion?
2. Installation
3. Usage
4. Local development
   • Requirements
   • Makefile commands
   • Structure
5. Contributing
6. Contact

About The Project

Orion-NAIS is a client to work with the NAIS API. It helps with authentication and provides a simple interface to work with the API.

When working with the API you need to have a valid token. The token is valid for a set period of time. The client will automatically refresh the token when it expires.

Why the name Orion?

The NAIS Api is provided through BarentsWatch. BarentsWatch is a Norwegian information portal that provides overview of activity and knowledge in coastal and sea areas. The Norwegian movie "Orion's Belt" from 1985 is an action movie set in the Barents region. About three men, a bulldozer, a Russian helicopter and a ship. Thus the name Orion.

Installation

Requires Python 3.10 or later.

pip install orion-nais

or using pipenv:

pipenv install orion-nais

or using poetry:

poetry add orion-nais

Usage

To install the package in your project run

poetry add orion-nais

then add an .env file to your project with the following variables:

CLIENT_ID=
CLIENT_SECRET=

If you don't have a client id and secret you can get one from your BarentsWatch account.

Then you can use the client like this:

from orion import Orion

orion = Orion()
# Get the last 24 hours of AIS data for a ship with MMSI XXXXXXXXXX
ais = orion.get_ais_last_24H(SHIP_MMSI)
# Convert the AIS data to a line
line = orion.ais_to_line(ais)

Local development

Requirements

• pyenv - manage python versions
• poetry - manage python dependencies

To install on mac you can use homebrew:

brew upgrade
brew install pyenv

You can either install poetry with homebrew or the way described in the documentation

Makefile commands

• make lint
  • lint the code in the src folder with black, isort and flake8. Mypy will check for correct typing.
• make format
  • format the code in the src folder with black and isort.
• make test
  • run the tests in the tests folder.
• make bump-patch
  • bump the patch version of the package. Example: 0.1.0 -> 0.1.1
• make bump-minor
  • bump the minor version of the package. Example: 0.1.0 -> 0.2.0
• make bump-major
  • bump the major version of the package. Example: 0.1.0 -> 1.0.0
• make release
  • publish the package to pypi. You need to have an account and be logged in to pypi.

Structure

.
├── .bumpversion.cfg
├── .editorconfig
├── .flake8
├── .gitignore
├── Makefile
├── README.md
├── orion
│   ├── client.py
│   ├── mmsi.py
│   ├── types
│   │   └── ais.py
│   ├── urls.py
│   ├── utils
│   │   └── get_data.py
│   └── vessel_codes.py
├── poetry.lock
├── pyproject.toml
└── tests
    ├── make_mock_data.py
    ├── mocks
    └── test_orion.py
    

• .bumpversion.cfg
  • Configuration file for bumpversion.
• .editorconfig
  • Configuration file for editorconfig.
• .flake8
  • Configuration file for flake8.
• .gitignore
  • Configuration file for git.
• pyproject.toml
  • Configuration file for poetry. Mypy and isort is configured here.
• poetry.lock
  • Lock file for poetry.
• Makefile
  • Makefile for the project. Here you can find commands for linting and formatting.
• README.md
  • This file.
• orion
  • The source code for the package.
  • client.py
    • The client class.
  • mmsi.py
    • A dataclass for handling MMSI numbers and MID-codes (jurisdiction).
  • types
    • A folder for types.
    • ais.py
      • A class for handling AIS messages.
  • urls.py
    • A file with urls for the API.
  • utils
    • A folder for utility functions.
    • get_data.py
      • A function for getting data from other sources. Not used by the Orion client. Contains code for getting data from the Norwegian Petroleum Directorate.
  • vessel_codes.py
    • A dataclass for looking up vessel codes.
• tests
  • Tests for the package.

Contributing

Do you have write permissions to the repo? Then you can clone this project to a folder on your computer.

git clone https://github.com/BergensTidende/orion-nais.git

If not do the following:

• Create a personal fork of the project on Github.
• Clone the fork on your local machine. Your remote repo on Github is called origin.
• Add the original repository as a remote called upstream.
• If you created your fork a while ago be sure to pull upstream changes into your local repository.

This will clone the repo into orion-nais.

Create a branch for your changes

git checkout -b name-of-branch

Make your changes, rememeber to commit. And always write your commit messages in the present tense. Your commit message should describe what the commit, when applied, does to the code – not what you did to the code.

If you're working on a clone push the branch to github and make PR.

If your're working a fork:

• Squash your commits into a single commit with git's interactive rebase. Create a new branch if necessary.
• Push your branch to your fork on Github, the remote origin.
• From your fork open a pull request in the correct branch. Target the project's develop branch if there is one, else go for master.
• If the maintainer requests further changes just push them to your branch. The PR will be updated automatically.
• Once the pull request is approved and merged you can pull the changes from upstream to your local repo and delete your extra branch(es).

Contact

Bord4 - [e-mail]