veronique 0.1.0__tar.gz

veronique-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.3
+Name: veronique
+Version: 0.1.0
+Summary: Private graph DB / social network
+Author: L3viathan
+Author-email: L3viathan <git@l3vi.de>
+Requires-Dist: sanic
+Requires-Dist: markdown-it-py[linkify]
+Requires-Dist: phonenumbers
+Requires-Python: >=3.9
+Project-URL: Repository, https://github.com/L3viathan/veronique
+Description-Content-Type: text/markdown
+
+# Véronique
+
+_A small database for storing entities, links between them and simple
+properties (e.g. text, color, numbers)._
+
+![a screenshot showing a basic detail view of an example entry](screenshot.png)
+
+Intended as a private social network/people database to help with memorizing
+facts about people, but there's not really any features specific to that.
+
+This is meant as a personal, intentionally non-scalable tool. As such, it uses
+SQLite, and there's no proper packaging yet (mostly because it's not needed).
+The app is protected from unauthenticated access, but beyond that there's no
+protection against e.g. XSS. This is a feature, you can put HTML into text
+fields for example. If you need SSO, MFA, or any other similar features, use a
+different tool.
+
+## Development
+
+- Clone the repo
+- Install `sanic`, `phonenumber`, and `markdown-it-py[linkify]` (to a venv)
+- _Either_: Place a file called `veronique_initial_pw` containing a password in
+  the working directory. This will be the password of the `admin` user.
+- _Or_: Run `python -m veronique.bootstrap` to fill the database with testing
+  data. The password of the admin user will be "admin". **This irrevocably
+  overwrites any existing db you may have.**
+- Run `sanic veronique:app --dev`
+
+## Deployment
+
+Running in production mostly means removing the `--dev` flag. Maybe set up a
+systemd service for it and point a reverse proxy at it or something. I
+personally [use
+ansible](https://github.com/L3viathan/ansibly/blob/master/roles/mainserver/tasks/veronique.yml)
+for deploying new versions.
+
+Missing migrations are automatically applied when restarting the app.
+
+## Concepts
+
+The database starts mostly empty, only a few internal verbs are added during
+the initial migration. There's also a fixed list of _data types_, since they
+need supporting Python code.
+
+### Claim
+
+A claim can be thought of as a simple sentence: It (normally) has a subject, a
+verb, and an object. For example, "John loves Mary", "Peter is 28 years old",
+or "Paul knows that [John loves Mary]".
+
+A subject is either another claim, or NULL. The latter is only possible when
+the verb is a special builtin one called `ROOT`. Root claims have no subject
+and have their name as their object. They represent any kind of entity.
+
+Now that we bootstrapped the world with root claims, we can talk about other
+types of claims: They (non-root claims) always have a subject claim (which can
+be, but doesn't have to be a root claim), a verb, and an object. The object can
+either be another claim (when the verb has the data type `directed_link` or
+`undirected_link`) or some atomic value (e.g. a number, a string, a date, ...).
+
+### Verb
+
+A verb has a similar function as it does in human language. You might also call
+it a property or a predicate. A verb always has a label (what it's called, e.g.
+`"loves"`), and a data type (see below). There's also a few built-in verbs that
+get special treatment:
+
+- `ROOT` (as described above)
+- `IS_A`: They have the data type `directed_link` and describe an is-a
+  relation. You could for example create a root fact called `"human"` and link
+  all people you create to it. There's special UI treatment for this relation
+  (it's displayed in the heading of the claim detail view). A claim can have
+  several `IS_A` links.
+- `VALID_FROM` and `VALID_UNTIL`: They have the data type `date` and describe
+  that a fact is only valid before or after a certain date. Invalid facts are
+  visible as such in the frontend.
+- `AVATAR`: A special field of type `picture` that will be used as the avatar
+  for facts in their detail view and almost all other references to it.
+- `COMMENT`: A regular `text` verb, except with special UI support.
+
+### Data type
+
+A data type describes what kind of object a claim of a certain verb can take.
+Notable data types are:
+
+- `directed_link`: This represents a regular link or transitive verb, e.g.
+  `"loves"`, `"is child of"`, etc.
+- `undirected_link`: These represent relationships that are by their nature
+  undirected. You could use this for `"friend of"`, `"partner of"`, `"works
+  with"`, or similar verbs, if you assume/model that this is never one-sided.
+- `string`, `number`, `text`, `boolean`: As you might expect, these are fairly
+  straightforward. Booleans get a checkbox as an input, string and text differ
+  by the size of their input controls (regular input vs. textarea).
+- `date`: Dates get special treatment in Véronique: You should enter them as
+  `%Y-%m-%d` ISO timestamps, _but_ you are allowed to replace any digit with a
+  question mark. This allows you to represent dates such as "some time in
+  1973" or "26th of July, but I don't know which year", which can be common
+  when entering data without full knowledge of the truth.
+- `inferred`: This is a special type for which you can't create any actual
+  claims. Instead, you need to define a set of rules by which this claim will
+  automatically be shown on claim detail pages. As this sounds pretty abstract,
+  here's an example: If you have a "child of" claim, you could create a
+  "sibling" claim based on the fact that siblings always have a shared parent.
+
+### Users
+
+Véronique now has basic support for additional users. Non-admin users can by
+default only see claims of a built-in type (e.g., root claims, labels,
+category, ...).
+
+You can then allow reading of other verbs per user, and also give _write_
+access to certain verbs. Non-admin users can only create claims of those verbs
+then, and can only edit claims they themselves have created.
+
+Users can also be allowed to see a set of allowed queries. Pretty much anything
+else is forbidden.

veronique-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Véronique
+
+_A small database for storing entities, links between them and simple
+properties (e.g. text, color, numbers)._
+
+![a screenshot showing a basic detail view of an example entry](screenshot.png)
+
+Intended as a private social network/people database to help with memorizing
+facts about people, but there's not really any features specific to that.
+
+This is meant as a personal, intentionally non-scalable tool. As such, it uses
+SQLite, and there's no proper packaging yet (mostly because it's not needed).
+The app is protected from unauthenticated access, but beyond that there's no
+protection against e.g. XSS. This is a feature, you can put HTML into text
+fields for example. If you need SSO, MFA, or any other similar features, use a
+different tool.
+
+## Development
+
+- Clone the repo
+- Install `sanic`, `phonenumber`, and `markdown-it-py[linkify]` (to a venv)
+- _Either_: Place a file called `veronique_initial_pw` containing a password in
+  the working directory. This will be the password of the `admin` user.
+- _Or_: Run `python -m veronique.bootstrap` to fill the database with testing
+  data. The password of the admin user will be "admin". **This irrevocably
+  overwrites any existing db you may have.**
+- Run `sanic veronique:app --dev`
+
+## Deployment
+
+Running in production mostly means removing the `--dev` flag. Maybe set up a
+systemd service for it and point a reverse proxy at it or something. I
+personally [use
+ansible](https://github.com/L3viathan/ansibly/blob/master/roles/mainserver/tasks/veronique.yml)
+for deploying new versions.
+
+Missing migrations are automatically applied when restarting the app.
+
+## Concepts
+
+The database starts mostly empty, only a few internal verbs are added during
+the initial migration. There's also a fixed list of _data types_, since they
+need supporting Python code.
+
+### Claim
+
+A claim can be thought of as a simple sentence: It (normally) has a subject, a
+verb, and an object. For example, "John loves Mary", "Peter is 28 years old",
+or "Paul knows that [John loves Mary]".
+
+A subject is either another claim, or NULL. The latter is only possible when
+the verb is a special builtin one called `ROOT`. Root claims have no subject
+and have their name as their object. They represent any kind of entity.
+
+Now that we bootstrapped the world with root claims, we can talk about other
+types of claims: They (non-root claims) always have a subject claim (which can
+be, but doesn't have to be a root claim), a verb, and an object. The object can
+either be another claim (when the verb has the data type `directed_link` or
+`undirected_link`) or some atomic value (e.g. a number, a string, a date, ...).
+
+### Verb
+
+A verb has a similar function as it does in human language. You might also call
+it a property or a predicate. A verb always has a label (what it's called, e.g.
+`"loves"`), and a data type (see below). There's also a few built-in verbs that
+get special treatment:
+
+- `ROOT` (as described above)
+- `IS_A`: They have the data type `directed_link` and describe an is-a
+  relation. You could for example create a root fact called `"human"` and link
+  all people you create to it. There's special UI treatment for this relation
+  (it's displayed in the heading of the claim detail view). A claim can have
+  several `IS_A` links.
+- `VALID_FROM` and `VALID_UNTIL`: They have the data type `date` and describe
+  that a fact is only valid before or after a certain date. Invalid facts are
+  visible as such in the frontend.
+- `AVATAR`: A special field of type `picture` that will be used as the avatar
+  for facts in their detail view and almost all other references to it.
+- `COMMENT`: A regular `text` verb, except with special UI support.
+
+### Data type
+
+A data type describes what kind of object a claim of a certain verb can take.
+Notable data types are:
+
+- `directed_link`: This represents a regular link or transitive verb, e.g.
+  `"loves"`, `"is child of"`, etc.
+- `undirected_link`: These represent relationships that are by their nature
+  undirected. You could use this for `"friend of"`, `"partner of"`, `"works
+  with"`, or similar verbs, if you assume/model that this is never one-sided.
+- `string`, `number`, `text`, `boolean`: As you might expect, these are fairly
+  straightforward. Booleans get a checkbox as an input, string and text differ
+  by the size of their input controls (regular input vs. textarea).
+- `date`: Dates get special treatment in Véronique: You should enter them as
+  `%Y-%m-%d` ISO timestamps, _but_ you are allowed to replace any digit with a
+  question mark. This allows you to represent dates such as "some time in
+  1973" or "26th of July, but I don't know which year", which can be common
+  when entering data without full knowledge of the truth.
+- `inferred`: This is a special type for which you can't create any actual
+  claims. Instead, you need to define a set of rules by which this claim will
+  automatically be shown on claim detail pages. As this sounds pretty abstract,
+  here's an example: If you have a "child of" claim, you could create a
+  "sibling" claim based on the fact that siblings always have a shared parent.
+
+### Users
+
+Véronique now has basic support for additional users. Non-admin users can by
+default only see claims of a built-in type (e.g., root claims, labels,
+category, ...).
+
+You can then allow reading of other verbs per user, and also give _write_
+access to certain verbs. Non-admin users can only create claims of those verbs
+then, and can only edit claims they themselves have created.
+
+Users can also be allowed to see a set of allowed queries. Pretty much anything
+else is forbidden.