First release

README.md

@@ -20,7 +20,3 @@ Have you got a small web application with a couple users and a database powered
 ```bash
 pip install alchemical_queues
 ```
-
-## Attributions
-
-The *Alchemical Queues* project was inspired by the [PQ](https://github.com/malthe/pq) project and borrows quite heavily from it from a design standpoint.

docs/api/core/AlchemicalEntry.md

@@ -0,0 +1 @@
+::: alchemical_queues.AlchemicalEntry

docs/api/core/AlchemicalQueue.md

@@ -0,0 +1 @@
+::: alchemical_queues.AlchemicalQueue

docs/api/core/AlchemicalQueues.md

@@ -0,0 +1 @@
+::: alchemical_queues.AlchemicalQueues

docs/api/core/AlchemicalResponse.md

@@ -0,0 +1 @@
+::: alchemical_queues.AlchemicalResponse

docs/api/tasks/QueuedTask.md

@@ -0,0 +1 @@
+::: alchemical_queues.tasks.QueuedTask

docs/api/tasks/Task.md

@@ -0,0 +1 @@
+::: alchemical_queues.tasks.Task

docs/api/tasks/TaskException.md

@@ -0,0 +1 @@
+::: alchemical_queues.tasks.TaskException

docs/api/tasks/TaskInfo.md

@@ -0,0 +1 @@
+::: alchemical_queues.tasks.TaskInfo

docs/api/tasks/Worker.md

@@ -0,0 +1 @@
+::: alchemical_queues.tasks.Worker

docs/api/tasks/task.md

@@ -0,0 +1 @@
+::: alchemical_queues.tasks.task

docs/development/contributing.md

@@ -0,0 +1 @@
+{% include "CONTRIBUTING.md" %}

docs/development/postgres.md

@@ -0,0 +1,9 @@
+# Testing against Postgres
+
+Running against postgres locally with a postgres docker
+
+```bash
+docker run --name postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=aq_db -p 5455:5432 postgres:latest
+export postgres_ip=`docker inspect -f '\{\{range.NetworkSettings.Networks\}\}\{\{.IPAddress\}\}\{\{end\}\}' postgres`
+pytest -x --engine "postgresql+psycopg2://postgres:postgres@${postgres_ip}/aq_db"
+```

docs/index.rst → docs/index.md

@@ -1,42 +1,5 @@
-=================
-Alchemical Queues
-=================
+# Welcome to Alchemical Queues
 
 Have you got a small web application with a couple users and a database powered by SQLAlchemy? Do you need to run a couple tasks in the background but does it feel like complete overkill to set up a Celery-based system and have to run a broker like Redis or RabbitMQ just for your three automated emails you send per day? Then you are the target audience of *Alchemical Queues*.
 
 *Alchemical Queues* is a small project that implements safe distributed queues on top of SQLAlchemy. On top of that is an implementation of task queues for which you can run one or more workers. Because it only has one dependency (SQLAlchemy) most likely you are just adding ~300 lines of python to your deployment with no additional external services required.
-
-
-Attributions
-============
-
-The *Alchemical Queues* project was inspired by the `PQ` project and borrows quite heavily from it from a design standpoint.
-
-
-Getting Started
-===============
-
-.. toctree::
-    :maxdepth: 1
-
-    installation
-    tutorial
-
-
-API Documentation
-=================
-
-.. toctree::
-    :maxdepth: 1
-
-    api.core
-    api.tasks
-
-
-Meta
-====
-
-.. toctree::
-    :maxdepth: 1
-
-    changelog

docs/stylesheets/extra.css

@@ -0,0 +1,7 @@
+
+/* Custom colors for Alchemical Queues docs */
+:root > * {
+  --md-primary-fg-color:        #7D8F69;
+  --md-primary-fg-color--light: #A9AF7E;
+  --md-primary-fg-color--dark:  #557153;
+}

docs/theme/partials/outdated.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version of the Alchemical Queues documentation.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest version.</strong>
+  </a>
+{% endblock %}

docs/usage/advanced.md

@@ -0,0 +1,69 @@
+# Extra functionality
+
+*Alchemical Queues* has a couple extra functionalities that you can combine to build your system.
+
+## Priority queues
+
+In reality, all *Alchemical Queues* are priority queues, just all normal items you insert have priority 0.
+
+```python
+queue = queues.get("priority-queue")
+queue.put(42, priority=12)
+queue.put(137, priority=13)
+queue.put(0)
+
+print(queue.get().data)  # prints 137
+print(queue.get().data)  # prints 42
+print(queue.get().data)  # prints 0
+```
+
+This argument also applies to the `schedule` method for tasks.
+
+```python
+add_numbers(1,2).schedule(queue, priority=12)
+```
+
+
+## Scheduling
+
+When putting things into the queue you can pass a `schedule_at` argument. These entries can not be popped off the queue before the `schedule_at` time.
+
+```python
+import time
+from datetime import datetime, timedelta
+
+now = datetime.now()
+queue = queues.get("schedule-queue")
+queue.put(42, schedule_at=now+timedelta(seconds=1))
+
+print(queue.get())  # will print None
+
+time.sleep(1.0)
+
+print(queue.get().data)  # will print 42
+```
+
+This argument also applies to the `schedule` method for tasks.
+
+```python
+add_numbers(1,2).schedule(queue, schedule_at=now+timedelta(seconds=30))
+```
+
+## Custom tables
+
+If you don't want to use the default `AlchemicalQueue` and `AlchemicalResponse` tables you can configure them.
+
+```python
+queues = AlchemicalQueues(
+    queue_tablename="queues",
+    response_tablename="responses"
+)
+```
+
+When you use `alchemical_worker` it will use the default names. You can run the worker via python on your custom queues.
+
+```python
+from alchemical_queues.tasks import Worker
+
+Worker(queues.get("task-queue")).work()
+```

docs/usage/flask_example.md

@@ -0,0 +1,62 @@
+# Flask-SQLAlchemy example
+
+This is a quick example of how to use `alchemical_queues.tasks` in a Flask context. We'll use the file `tasks.py` from the main tutorial:
+
+```python
+from alchemical_queues.tasks import task
+
+@task
+def add_numbers(taskinfo, a, b):
+    print(f"Running {a}+{b}")
+    return a + b
+```
+
+The minimal Flask app looks like this:
+
+```python
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+from alchemical_queues import AlchemicalQueues
+from tasks import add_numbers
+
+
+db = SQLAlchemy()
+app = Flask(__name__)
+app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///project.db"
+db.init_app(app)
+
+queues = AlchemicalQueues()
+
+with app.app_context():
+    db.create_all()
+    queues.set_engine(db.engine)
+    queues.create_all()
+
+
+@app.route("/<int:a>/<int:b>")
+def add_some_numbers(a: int, b: int):
+    task_queue = queues.get("task-queue")
+    entry = add_numbers(a, b).schedule(task_queue)
+    return f"task: {entry.entry_id}"
+
+
+@app.route("/result/<int:entry>")
+def result(entry: int):
+    task_queue = queues.get("task-queue")
+    task = add_numbers.retrieve(task_queue, entry)
+
+    if task.result is None:
+        return "No result yet"
+    else:
+        return f"result: {task.result}"
+
+
+if __name__ == "__main__":
+    app.run()
+```
+
+The worker can be run like this:
+
+```bash
+alchemical_worker "sqlite:///project.db" task-queue
+```

docs/usage/installation.md

@@ -0,0 +1,23 @@
+# Installation
+
+You can install *Alchemical Queues* using pip:
+
+```bash
+pip install alchemical_queues
+```
+
+You can also install from source:
+```bash
+git clone https://github.com/thijsmie/alchemical_queues
+cd alchemical_queues
+pip install .
+```
+
+You can also use poetry to set up your development environment and run the tests:
+```bash
+git clone https://github.com/thijsmie/alchemical_queues
+cd alchemical_queues
+pip install poetry
+poetry install
+poetry run pytest
+```