docs: Add info about custom serializer and types; contributing guide

.github/workflows/test.yaml

@@ -13,20 +13,24 @@ defaults:
 jobs:
   unit_tests:
     strategy:
+      fail-fast: false
       matrix:
         python-version: [ "3.9", "3.10", "3.11", "3.12" ]
         os: [ ubuntu-latest, windows-latest, macos-latest ]
 
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
 
       - name: Setup the Python Environment ${{ matrix.python-version }}
-        uses: Qwerty-133/python-setup@v1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          skip-pre-commit: true
+          cache: "poetry"
 
       - name: Install dependencies
         run: |
@@ -37,7 +41,7 @@ jobs:
           poetry run pytest .
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
   mypy:
@@ -48,13 +52,16 @@ jobs:
         python-version: [ "3.9", "3.10", "3.11", "3.12" ]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
 
       - name: Setup the Python Environment ${{ matrix.python-version }}
-        uses: Qwerty-133/python-setup@v1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          skip-pre-commit: true
+          cache: "poetry"
 
       - name: Install dependencies
         run: |
@@ -75,13 +82,16 @@ jobs:
         python-version: [ "3.9", "3.10", "3.11", "3.12" ]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
 
       - name: Setup the Python Environment ${{ matrix.python-version }}
-        uses: Qwerty-133/python-setup@v1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          skip-pre-commit: true
+          cache: "poetry"
 
       - name: Install dependencies
         run: |
@@ -99,13 +109,16 @@ jobs:
         python-version: [ "3.12" ]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
 
       - name: Setup the Python Environment ${{ matrix.python-version }}
-        uses: Qwerty-133/python-setup@v1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          skip-pre-commit: true
+          cache: "poetry"
 
       - name: Install dependencies
         run: |

.github/workflows/upload.yaml

@@ -22,13 +22,16 @@ jobs:
         python-version: [ "3.12" ]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
 
       - name: Setup the Python Environment ${{ matrix.python-version }}
-        uses: Qwerty-133/python-setup@v1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          skip-pre-commit: true
+          cache: "poetry"
 
       - name: Install dependencies
         run: poetry install

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributors Guide
+
+Welcome to our project! We value your contributions and want to make it easy for you to get involved. This guide outlines our project's workflow, versioning strategy, and commit message conventions.
+
+## Workflow: GitHub Flow
+
+To get started with contributing, please follow the GitHub Flow:
+
+1. **Fork** this repository to your own GitHub account.
+2. **Clone** the forked repository to your local machine:
+    ```bash
+    git clone <your-fork-url>
+    git checkout -b your-new-branch-name
+    ```
+3. **Create a branch** for your modifications:
+    ```bash
+    git checkout -b feature-branch-name
+    ```
+4. **Make your changes** and commit them using the [Conventional Commits](#commit-messages) format.
+5. **Push** your branch to your fork:
+    ```bash
+    git push origin feature-branch-name
+    ```
+6. **Create a pull request** against the original repository’s main branch.
+7. **Review** the changes with maintainers and **address any feedback**.
+
+The project maintainers will merge the changes once they are approved. If you have any questions or need help, please feel free to reach out to us.
+
+## Semantic Versioning
+
+Our project adheres to Semantic Versioning (SemVer) principles, which helps us manage releases and dependencies systematically. The version number format is:
+
+MAJOR.MINOR.PATCH
+
+- **MAJOR**: Incompatible API changes,
+- **MINOR**: Additions that are backward compatible,
+- **PATCH**: Backward-compatible bug fixes.
+
+## Commit Messages
+
+We use the Conventional Commits format for our commit messages to facilitate consistency and changelog generation. Please structure your commits as follows:
+
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+
+markdown
+
+
+### Commit Types <type>
+
+- `feat`: Introduces a new feature.
+- `fix`: Patches a bug.
+- `docs`: Documentation only changes.
+- `style`: Code style update (formatting, semi-colons, etc.).
+- `refactor`: Neither fixes a bug nor introduces a feature.
+- `perf`: Performance improvements.
+- `test`: Adding missing tests or correcting existing ones.
+- `chore`: Other changes that don't modify src or test files.
+
+**Example Commit Message**:
+
+```
+feat(authentication): add biometric login support
+
+- Support fingerprint and face recognition login.
+- Ensure compatibility with mobile devices.
+```
+
+Thank you for contributing to our project! We appreciate your effort to follow these guidelines.

README.md

@@ -14,7 +14,7 @@ Package that integrates NumPy Arrays into Pydantic!
 - `pydantic_numpy.typing` provides many typings such as `NpNDArrayFp64`, `Np3DArrayFp64` (float64 that must be 3D)! Works with both `pydantic.BaseModel` and `pydantic.dataclass`
 - `NumpyModel` (derived from `pydantic.BaseModel`) make it possible to dump and load `np.ndarray` within model fields alongside other fields that are not instances of `np.ndarray`!
 
-See the [`test.helper.groups`](https://github.com/caniko/pydantic-numpy/blob/trunk/tests/helper/groups.py) to see types that are defined explicitly. Define your own NumPy types with `pydantic_numpy.np_array_pydantic_annotated_typing`.
+See the [`test.helper.testing_groups`](https://github.com/caniko/pydantic-numpy/blob/trunk/tests/helper/testing_groups.py) to see types that are defined explicitly.
 
 ### Examples
 
@@ -69,16 +69,45 @@ cfg.dump("path_to_dump_dir", "object_id")
 equals_cfg = model_agnostic_load("path_to_dump_dir", "object_id", models=[MyNumpyModel, MyDemoModel])
 ```
 
+### Custom type
+There are two ways to define. Function derived types with `pydantic_numpy.helper.annotation.np_array_pydantic_annotated_typing`.
+
+Function derived types don't work with static type checkers like Pyright and MyPy. In case you need the support,
+just create the types yourself:
+
+```python
+NpStrict1DArrayInt64 = Annotated[
+    np.ndarray[tuple[int], np.dtype[np.int64]],
+    NpArrayPydanticAnnotation.factory(data_type=np.int64, dimensions=1, strict_data_typing=True),
+]
+```
+
+#### Custom serialization
+
+If the default serialization of NumpyDataDict, as outlined in [typing.py](https://github.com/caniko/pydantic-numpy/blob/trunk/pydantic_numpy/helper/typing.py), doesn't meet your requirements, you have the option to define a custom type with its own serializer. This can be achieved using the NpArrayPydanticAnnotation.factory method, which accepts a custom serialization function through its serialize_numpy_array_to_json parameter. This parameter expects a function of the form `Callable[[npt.ArrayLike], Iterable]`, allowing you to tailor the serialization process to your specific needs.
+
+Example below illustrates definition of 1d-array of `float32` type that serializes to flat Python list (without nested dict as in default `NumpyDataDict` case):
+
+```python
+def _serialize_numpy_array_to_float_list(array_like: npt.ArrayLike) -> Iterable:
+    return np.array(array_like).astype(float).tolist()
+
+
+Np1DArrayFp32 = Annotated[
+    np.ndarray[tuple[int], np.dtype[np.float32]],
+    NpArrayPydanticAnnotation.factory(
+        data_type=np.float32,
+        dimensions=1,
+        strict_data_typing=False,
+        serialize_numpy_array_to_json=_serialize_numpy_array_to_float_list,
+    ),
+]
+```
+
 ### Install
 ```shell
 pip install pydantic-numpy
 ```
 
-## Considerations
-The package is designed to work with Pydantic V2 and not V1. You can install from [cheind's](https://github.com/cheind/pydantic-numpy) repository if you want Python `<=3.8` and Pydantic V1 support.
-
-### Licensing notice
-As of version `3.0.0` the license has moved over to BSD-4. The versions prior are under the MIT license.
-
 ### History
 The original idea originates from [this discussion](https://gist.github.com/danielhfrank/00e6b8556eed73fb4053450e602d2434), and forked from [cheind's](https://github.com/cheind/pydantic-numpy) repository.