Make the Documentation

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Documentation Building
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+  schedule:
+    - cron: 0 7 * * 1  # 7 A.M. mon
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Docs Building
+    runs-on: ubuntu-latest
+    if: "!(contains(github.event.head_commit.message, '[skip ci]') || contains(github.event.head_commit.message, '[ci skip]'))"
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+        cache: pip
+        cache-dependency-path: '**/pyproject.toml'
+    - name: Install base dependencies
+      run: pip install -U -q pip setuptools
+    - name: Install package dependencies
+      run: pip install -U -q .[docs]
+    - name: Build with Sphinx
+      run: |
+        cd docs
+        make html
+
+  doctest:
+    name: Documentation Testing
+    runs-on: ubuntu-latest
+    if: "!(contains(github.event.head_commit.message, '[skip ci]') || contains(github.event.head_commit.message, '[ci skip]'))"
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+        cache: pip
+        cache-dependency-path: '**/pyproject.toml'
+    - name: Install base dependencies
+      run: pip install -U -q pip setuptools
+    - name: Install pytest
+      run: pip install -U -q pytest pytest-doctestplus
+    - name: Install package dependencies
+      run: pip install -U .[docs] .[test]
+    - name: Run pytest on docs
+      run: pytest --doctest-rst --doctest-plus docs

.github/workflows/python-publish.yml

@@ -19,6 +19,7 @@ jobs:
   publish-pypi:
     name: Build and publish to PyPi
     runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
     steps:
     - uses: actions/checkout@master
       with:
@@ -41,7 +42,6 @@ jobs:
         --wheel
         --outdir dist/
     - name: Publish package to PyPi
-      if: github.ref == 'refs/heads/main'
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
         password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -1,5 +1,11 @@
 .vscode
 version.py
+# files that may be created during tests
+*.db
+
+# docs generated files
+docs/_build
+docs/api
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.readthedocs.yaml

@@ -0,0 +1,30 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+   - pdf
+   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -1,6 +1,6 @@
 # DBasTable
 
-[![Unit Tests](https://github.com/juliotux/DBasTable/actions/workflows/unittests.yml/badge.svg)](https://github.com/juliotux/DBasTable/actions/workflows/unittests.yml) [![codecov](https://codecov.io/gh/juliotux/DBasTable/graph/badge.svg?token=r9kulm3ANZ)](https://codecov.io/gh/juliotux/DBasTable)
+[![Unit Tests](https://github.com/juliotux/DBasTable/actions/workflows/unittests.yml/badge.svg)](https://github.com/juliotux/DBasTable/actions/workflows/unittests.yml) [![codecov](https://codecov.io/gh/juliotux/DBasTable/graph/badge.svg?token=r9kulm3ANZ)](https://codecov.io/gh/juliotux/DBasTable) [![Documentation Status](https://readthedocs.org/projects/dbastable/badge/?version=latest)](https://dbastable.readthedocs.io/en/latest/?badge=latest)
 
 A simplier way to access SQLite tables, just like Numpy structured arrarys or Pandas dataframes.
 
@@ -29,3 +29,41 @@ As menioned above, we intended to perform only simple operations with this packa
 I'm not a SQL master, nor a digital security guru. I'm an astrophysicist that do some python. So, if you want to use it, use with care.
 
 # Install and Documentation
+
+## Installation
+
+The easiest way to install dbastable is via [pip](https://pip.pypa.io/en/stable/)
+
+```
+pip install dbastable
+```
+
+Alternatively, you can clone the repository and install it manually:
+
+```
+git clone
+cd dbastable
+pip install -U .
+```
+
+or
+
+```
+pip install -U git+https://github.com/juliotux/dbastable
+```
+
+Development version is also available in pip:
+
+```
+pip install -U --pre dbastable
+```
+
+
+## Documentation
+
+
+The documentation is available at https://dbastable.readthedocs.io/en/latest/
+
+# License
+
+`dbastable` is licensed under the terms of the [MIT license](https://opensource.org/license/mit/). See the file `LICENSE` for information on the history of this software, terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.

dbastable/_sanitizer.py

@@ -1,5 +1,6 @@
 import numpy as np
 import base64
+import math
 
 from ._def import _B32_COL_PREFIX, _ID_KEY
 
@@ -9,8 +10,8 @@ def _colname_to_b32_decode(string):
     # ensure remove the prefix
     string = string.lstrip(_B32_COL_PREFIX)
     # base32 need 8 chars padding
-    remainder = len(string) % 8
-    string += '='*(8-remainder)
+    pad = math.ceil(len(string) / 8) * 8 - len(string)
+    string += '='*pad
     return string
 
 
@@ -36,12 +37,13 @@ def _sanitize_key(self, key):
         # TODO: check for protected names
         if key.startswith(_B32_COL_PREFIX) or key == _ID_KEY:
             raise ValueError(f'{key} uses a protected name.')
-        if len([ch for ch in key if not ch.isalnum() and ch != '_']) != 0:
+        if len([ch for ch in key if not ch.isalnum() and ch != '_']) != 0 \
+           or key[0].isdigit():
             # if a name is invalid, encode it in base32 and add a prefix
             # if it is allowed
             if self._allow_b32_colnames:
                 return self._encode_b32(key)
-            raise ValueError(f'Invalid column name: {key}.')
+            raise ValueError(f'Invalid column name: {key}')
         return key.lower()
 
     def _sanitize_colnames(self, data):