Merge pull request #92 from aaxelb/10311-osf-extract

[ENG-10311] improvements from osf-metrics (and more)

Author: aaxelb

.gitignore

@@ -28,6 +28,9 @@ var/
 pip-log.txt
 pip-delete-this-directory.txt
 
+# mypy
+.dmypy.json
+
 # Unit test / coverage reports
 htmlcov/
 .tox/

.konchrc

@@ -7,10 +7,9 @@ from django.conf import settings
 from django.utils.termcolors import colorize
 from django.apps import apps
 import konch
-import elasticsearch_dsl
-from elasticsearch_dsl import connections, Search
+import elasticsearch8
 
-from elasticsearch_metrics.registry import registry
+from elasticsearch_metrics.registry import djelme_registry
 from elasticsearch_metrics.management.color import color_style
 
 
@@ -19,9 +18,9 @@ from elasticsearch_metrics.management.color import color_style
 #   'context_format', 'ipy_extensions', 'ipy_autoreload',
 #   'ipy_colors', 'ipy_highlighting_style'
 context = {
-    "dsl": elasticsearch_dsl,
-    "Search": Search,
-    "registry": registry,
+    "dsl": elasticsearch8.dsl,
+    "Search": elasticsearch8.dsl.Search,
+    "registry": djelme_registry,
     "apps": apps,
     "settings": settings,
     "style": color_style(),
@@ -41,10 +40,11 @@ def setup():
     # Set up django and add the default elasticsearch-py client and Metric to the context
     os.environ.setdefault("DJANGO_SETTINGS_MODULE", "elasticsearch_metrics.tests.settings")
     django.setup()
-    from elasticsearch_metrics.metrics import Metric
+    from elasticsearch_metrics.imps.elastic8 import EventRecord, CyclicRecord
 
-    context["client"] = connections.get_connection()
-    context["Metric"] = Metric
+    context["client"] = elasticsearch8.dsl.connections.get_connection()
+    context["EventRecord"] = EventRecord
+    context["CyclicRecord"] = CyclicRecord
     konch.config({"context": context})
 
 

CONTRIBUTING.md

@@ -1,29 +1,51 @@
 # Contributing
 (TODO: update)
 
-## Setting up for development
+## Code conventions
 
-* Create and activate a new virtual environment
-* `pip install -e '.[dev]'`
-* Install django: `pip install django`
-* (Optional but recommended) Run elasticsearch: `docker-compose up`
 
-* Run tests and checks:
+## Setting up local devloop
 
+### 0. get the code
+for example:
 ```
-# Run all tests (requires elasticsearch to be running)
-python3 -m elasticsearch_metrics.tests
+git clone https://github.com/CenterForOpenScience/django-elasticsearch-metrics.git djelme
+cd djelme
 ```
+
+### 1. put environment together
+create and activate a [python virtual environment](https://docs.python.org/3.14/tutorial/venv.html)
+with python version 3.10+ -- there are many tools for this; you may already have your own way.
+
+here's an example using `venv` (in python's standard lib) to create the virtual environment in a `.venv` directory, with bash:
 ```
-# Run only linting (not tests)
-python3 -m elasticsearch_metrics.tests --lint
+python -m venv .venv && source .venv/bin/activate
 ```
+
+install dependencies (listed in `pyproject.toml`), including the `dev` extra (and maybe `anydjango`) -- here's an example using `pip`:
 ```
-# Run only tests (not linting)
-python3 -m elasticsearch_metrics.tests --test
+pip install -e '.[dev,anydjango]'
 ```
 
-* Run the shell with:
+### Run tests and checks
+
+these expect elasticsearches to be running and configured in `elasticsearch_metrics/tests/settings.py` (or set environment variables `ELASTICSEARCH6_URL` and `ELASTICSEARCH8_URL`) -- see `using docker-style container tools`, below, for one way to do that
+
+running the python module `elasticsearch_metrics.tests` will run tests and linting checks
+-- should always pass before merging to `main`
+
+```
+python -m elasticsearch_metrics.tests
+```
+optional args:
+- `--devloop`: adds `--failfast --pdb` to test args
+- `--coverage`: print code coverage report
+- `--test`: run only tests (not linting)
+- `--lint`: run only linting checks (not tests)
+
+see `elasticsearch_metrics/tests/__main__.py` for more details
+
+### Run the shell with:
 
 ```
 konch allow
@@ -43,3 +65,23 @@ Run the tests with tox:
 ```
 tox
 ```
+
+### (optional) using docker-style container tools
+see `testbox.Containerfile` and `docker-compose.yml` -- running `testbox` runs `python -m elasticsearch_metrics.tests`
+
+(note: examples use `pc` aliased to a `docker-compose` equivalent)
+
+start elasticsearches in the background
+```
+pc up -d elasticsearch6 elasticsearch8
+```
+
+run tests and lint
+```
+pc up testbox
+```
+
+example devloop -- use current code, debugger on error, stop on failure
+```
+pc run --build --rm --no-deps testbox poetry run python -m elasticsearch_metrics.tests --devloop
+```