chore: add proj.py venv, document it, add one simple example sending two lines

Author: marregui

.gitignore

@@ -107,6 +107,7 @@ celerybeat.pid
 *.sage.py
 
 # Environments
+.idea
 .env
 .venv
 env/

DEV_NOTES.rst

@@ -19,23 +19,36 @@ Install Rust as per https://rustup.rs/.
 
     curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
-Install Cython:
+Install your local Python3 environment **venv**
+
+.. code-block:: bash
+
+    python3 -m venv venv
+    venv/bin/python install -U pip
+    venv/bin/python install -r dev_requirements.txt
+
+    # or simply:
+    python3 proj.py venv
+
+    # either of the ^ ^ should be followed by:
+    source venv/bin/activate
+
+The development requirements are these if you prefer to install them one by one:
+
+- Install Cython:
 
 .. code-block:: bash
 
     python3 -m pip install cython
 
-Documentation
--------------
+- Documentation
 
 .. code-block:: bash
 
     python3 -m pip install sphinx
     python3 -m pip install sphinx_rtd_theme
 
-
-Packaging and releasing
------------------------
+- Packaging and releasing
 
 .. code-block:: bash
 
@@ -87,7 +100,7 @@ MacOS Apple Silicon, run:
 .. code-block:: bash
 
     python3 proj.py sdist   # source distribution
-    python3 proj.py cibuildwheel
+    python3 proj.py cibuildwheel # the order of these two lines does not matter
 
 This will end up putting everything in the ``dist/`` directory.
 

dev_requirements.txt

@@ -0,0 +1,8 @@
+setuptools>=45.2.0
+Cython>=0.29.24
+wheel>=0.34.2
+cibuildwheel>=2.8.0
+Sphinx>=5.0.2
+sphinx-rtd-theme>=1.0.0
+twine>=4.0.1
+bump2version>=1.0.1

examples/line_sender_example.py

@@ -0,0 +1,15 @@
+from questdb.ilp import Sender, TimestampNanos
+
+if __name__ == '__main__':
+    with Sender('localhost', 9009) as sender:
+        sender.row(
+            'line_sender_example',
+            symbols={'id': 'OMEGA'},
+            columns={'price': '111222233333i', 'qty': 3.5}
+        )
+        sender.row(
+            'line_sender_example',
+            symbols={'id': 'OMEGA'},
+            columns={'price': '111222233330i', 'qty': 2.5}
+        )
+        sender.flush()

proj.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 
 import sys
+
 sys.dont_write_bytecode = True
 import os
 import shutil
@@ -10,7 +11,6 @@
 import glob
 import platform
 
-
 PROJ_ROOT = pathlib.Path(__file__).parent
 
 
@@ -53,11 +53,11 @@ def _arg2bool(arg):
     return arg.lower() in ('true', 'yes', '1')
 
 
-COMMANDS = set()
+COMMANDS = []
 
 
 def command(fn):
-    COMMANDS.add(fn.__name__)
+    COMMANDS.append(fn.__name__)
     return fn
 
 
@@ -67,28 +67,28 @@ def build():
 
 
 @command
-def serve(port=None):
-    port = port or 8000
-    docs_dir = PROJ_ROOT / 'build' / 'docs'
-    _run('python3', '-m', 'http.server', port, cwd=docs_dir)
+def test(all=False, patch_path='1', *args):
+    env = {'TEST_QUESTDB_PATCH_PATH': patch_path}
+    if _arg2bool(all):
+        env['TEST_QUESTDB_INTEGRATION'] = '1'
+    _run('python3', 'test/test.py', '-v', *args,
+         env=env)
 
 
 @command
 def doc(http_serve=False, port=None):
     _run('python3', '-m', 'sphinx.cmd.build',
-        '-b', 'html', 'docs', 'build/docs',
-        env={'PYTHONPATH': str(PROJ_ROOT / 'src')})
+         '-b', 'html', 'docs', 'build/docs',
+         env={'PYTHONPATH': str(PROJ_ROOT / 'src')})
     if _arg2bool(http_serve):
         serve(port)
 
 
 @command
-def test(all=False, patch_path='1', *args):
-    env = {'TEST_QUESTDB_PATCH_PATH': patch_path}
-    if _arg2bool(all):
-        env['TEST_QUESTDB_INTEGRATION'] = '1'
-    _run('python3', 'test/test.py', '-v', *args,
-        env=env)
+def serve(port=None):
+    port = port or 8000
+    docs_dir = PROJ_ROOT / 'build' / 'docs'
+    _run('python3', '-m', 'http.server', port, cwd=docs_dir)
 
 
 @command
@@ -105,11 +105,16 @@ def cibuildwheel(*args):
         # Python version.
         python = '/Library/Frameworks/Python.framework/Versions/3.8/bin/python3'
     _run(python, '-m',
-        'cibuildwheel',
-        '--platform', plat,
-        '--output-dir', 'dist',
-        '--archs', platform.machine(),
-        *args)
+         'cibuildwheel',
+         '--platform', plat,
+         '--output-dir', 'dist',
+         '--archs', platform.machine(),
+         *args)
+
+
+@command
+def cw(*args):
+    cibuildwheel(args)
 
 
 @command
@@ -133,6 +138,17 @@ def clean():
     _rm(PROJ_ROOT / 'src', '**/*.html')
 
 
+@command
+def venv():
+    if pathlib.Path('venv').exists():
+        sys.stderr.write('venv already exists, delete it, or run command clean\n')
+        return
+    _run('python3', '-m', 'venv', 'venv')
+    _run('venv/bin/python3', '-m', 'pip', 'install', '-U', 'pip')
+    _run('venv/bin/python3', '-m', 'pip', 'install', '-r', 'dev_requirements.txt')
+    sys.stdout.write('NOTE: remember to activate the environment: source venv/bin/activate\n')
+
+
 def main():
     if len(sys.argv) < 2:
         sys.stderr.write('Usage: python3 proj.py <command>\n')