adds type annotations, move netcdf utils to io module

.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4

.github/actions/setup/action.yml

@@ -0,0 +1,21 @@
+name: "setup"
+description: "setup python"
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/checkout@v4
+    - name: "install"
+      uses: mamba-org/setup-micromamba@v1
+      with:
+        micromamba-version: '2.0.5-0' # from https://github.com/mamba-org/micromamba-releases
+        environment-file: environment.yml
+        cache-environment: true
+        post-cleanup: 'none'
+        create-args: >-
+          python=3.12
+          black
+          mypy
+          isort
+          ruff
+

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+defaults:
+  run:
+    shell: bash -leo pipefail {0}
+
+jobs:
+  black:
+    name: black
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: black
+        run: "python -m black --check ."
+  isort:
+    name: isort
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: isort
+        run: "python -m isort -c -v ."
+  lint:
+    name: ruff
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: lint
+        run: "python -m ruff check"
+  mypy:
+    name: mypy
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: mypy
+        run: "python -m mypy ."
+  test:
+    name: unittest
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: test
+        run: "python -m unittest discover -v"
+
+

.gitignore

@@ -1,125 +1,27 @@
-# Created by .ignore support plugin (hsz.mobi)
-### JetBrains template
-# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
-# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+# IDEs / editors
 .idea
-
-## Plugin-specific files:
-
-# IntelliJ
-/out/
-
-# mpeltonen/sbt-idea plugin
-.idea_modules/
-
-# JIRA plugin
-atlassian-ide-plugin.xml
-
-# Crashlytics plugin (for Android Studio and IntelliJ)
-com_crashlytics_export_strings.xml
-crashlytics.properties
-crashlytics-build.properties
-fabric.properties
-### Vim template
-# swap
-[._]*.s[a-w][a-z]
-[._]s[a-w][a-z]
-# session
-Session.vim
-# temporary
-.netrwhist
-*~
-# auto-generated tag files
-tags
-### Python template
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
+*.swo
+*.swp
+.zed
 
 # Distribution / packaging
-.Python
-env/
-build/
-develop-eggs/
 dist/
-downloads/
+build/
 eggs/
 .eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
 
 # Unit test / coverage reports
 htmlcov/
-.tox/
 .coverage
 .coverage.*
 .cache
 nosetests.xml
 coverage.xml
-*,cover
-.hypothesis/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-
-# dotenv
-.env
 
 # virtualenv
 .venv/
 venv/
-ENV/
-
-# Spyder project settings
-.spyderproject
-
-# Rope project settings
-.ropeproject
 
+# Tools
+.mypy_cache/
+.ruff_cache/

CHANGELOG.md

@@ -1,36 +1,44 @@
-# v0.3.3 - 2024 04 08
+# v1.0.0 - 2022-12-27
+- Adds type annotations and `py.typed` marker.
+- Replaces asserts with proper checks and custom exceptions
+- Change (breaking!): remove netcdf read/write FlagWrap instance methods
+- Adds netcdf read/write utils in a new `io` module
+    - Use `from ncflag.io import read_flag_from_netcdf, write_flag_to_netcdf`
+    - Replace `FlagWrap.init_from_netcdf(...)` with `read_flag_from_netcdf(...)`
+    - Replace `FlagWrap.write_to_netcdf(...)` with `write_flag_to_netcdf(...)`
+- Change CLI options to dash word separators (`-`). `--show_flags` ->
+  `--show-flags` and `--use_time_var` -> `--use-time-var`.
 
+# v0.3.3 - 2024 04 08
 - Bug fix: compatibility with numpy 1.24+ new out-of-bounds int conversion failure 
   https://numpy.org/devdocs/release/1.24.0-notes.html#conversion-of-out-of-bound-python-integers
 
-# v0.3.2 - 2022 10 02
-
+# v0.3.2 - 2022-10-02
 - use long_description_content_type="text/markdown" in setup.py
 - unpin click dep, tested with latest 8.1.3
 
-# v0.3.1 - 2022 06 26
-
+# v0.3.1 - 2022-06-26
 - `ignore_missing` option on `get_flag` to bitwise and flag meanings, but not raise exception if a
   meaning is missing from the flag.
 
-# v0.3.0 - 2020 12 11
+# v0.3.0 - 2020-12-11
  - New method: `FlagWrap.is_valid_meaning` for convenience.
  - Change reduce method to exclude _entire_ flag vectors (all bits) from reduction if any bits in
    the exclude_mask are set.
  - Make FlagWrap.flag_meanings "public" (prev. FlagWrap._flag_meanings)
  - Adds name attribute, available from init as kwarg, for misc use.
  - Drops support for Python 2.7
 
-# v0.2.6 - 2020 04 03
+# v0.2.6 - 2020-04-03
  - Bug fix: cli: fix `--show_flags` option not working for Python 3
 
-# v0.2.5 - 2019 12 16
+# v0.2.5 - 2019-12-16
  - cli: Support Python 3 by removing relative import.
  - setup.py move to `convert_file` from deprecated pypandoc `convert`
  - Adds shape, fill shortcuts for `init_from_netcdf`
  - Persist internal reference to netcdf object for convenience in `write_to_netcdf`.
 
-# v0.2.0 - 2018 09 25
+# v0.2.0 - 2018-09-25
  - netcdf agnostic, just need flag_meanings, flag_values, and optionally
 flag_masks.
  - Previous FlagWrap(netcdf.Variable) construction should be replaced with
@@ -41,17 +49,17 @@ FlagWrap.write_to_netcdf(netcdf.Variable).
  - Fixed bug in setting mutually exclusive flag_meanings.
  - Added comprehensive testing.
 
-# v0.1.1 - 2018 06 05
+# v0.1.1 - 2018-06-05
  - Add reset and init to custom value other than 0.
 
-# v0.1.0 - 2018 06 05
+# v0.1.0 - 2018-06-05
  - Fix method for setting flags. Previous method did not
     work properly in some cases, eg. good_quality_qf. Now
     clears bits in flag under the mask before setting value.
  - Adds a get_mask_for_meaning function.
  - Improves documentation and testing.
 
-# v0.0.3 - 2018 05 31
+# v0.0.3 - 2018-05-31
  - Handle flags that are set to fill values, by definition, no flags are
     set when the value is filled.
 
@@ -62,6 +70,6 @@ FlagWrap.write_to_netcdf(netcdf.Variable).
  - Optimization: exit_on_good option for get_flags_set_at_index. If known
     that no other flags can be set on "good" flag and good flag == 0, skip
     extra work of searching through all other flags.
- - New: get_value_for_meaning function. Use case eg: start by setting all 
+ - New: get_value_for_meaning function. Use case eg: start by setting all
     flags to a "missing_data" value, but avoid hard coding the "missing_data"
     value.