add examples (#13)

* add examples

* dont test example code

* dont fmt examples

.github/workflows/pr.yml

@@ -50,9 +50,13 @@ jobs:
             exit 1
           fi
       - run: rye fmt --check
+        working-directory: py
       - run: rye lint
+        working-directory: py
       - run: rye run check
+        working-directory: py
       - run: rye run test
+        working-directory: py
 
   test-rust:
     runs-on: ubuntu-latest
@@ -62,6 +66,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - run: cargo fmt --check
+        working-directory: upid_rs
       - run: cargo clippy
         working-directory: upid_rs
       - run: cargo test --all-features

Cargo.toml

@@ -3,6 +3,7 @@ resolver = "2"
 members = [
   "upid_pg",
   "upid_rs",
+  "examples/rust",
 ]
 
 [profile.dev]

README.md

@@ -40,6 +40,14 @@ with psycopg.connect("postgresql://...") as conn:
     print(res)          # user_2accvpp5guht4dts56je5a
 ```
 
+## Examples
+You can try out the Python and Rust examples in this repository.
+They both involve spinning up a Postgres DB and inserting a UPID as itself, as a UUID and as text.
+- [./examples/python](./examples/python)
+- [./examples/rust](./examples/rust)
+
+There are also TypeScript examples for browser and Node (with Postgres) in the [upid-ts](https://github.com/carderne/upid-ts) repo.
+
 ## Demo
 You can give it a spin at [upid.rdrn.me](https://upid.rdrn.me/).
 

examples/python/.mise.toml

@@ -0,0 +1,2 @@
+[env]
+_.python.venv='.venv'

examples/python/README.md

@@ -0,0 +1,31 @@
+# example-python
+
+Clone this repo:
+```bash
+git clone [email protected]:carderne/upid.git
+cd upid/examples/python
+```
+
+Get a Docker image running:
+```bash
+docker run --rm -e POSTGRES_PASSWORD=mypassword \
+  -p 5432:5432 --detach carderne/postgres-upid:16
+```
+
+Install requirements:
+```bash
+pip install -r requirements.txt
+```
+
+
+Run the script:
+```bash
+python example.py
+
+# Extension ready
+# Table created
+# Inserted:
+# id_upid=user_2acqxw7dpigf2y345ug7ia
+# id_uuid=01916ef0-a9ab-98b0-7822-1e985ed61576
+# id_text=user_2acqxw7dpigf2y345ug7ia
+```

examples/python/example.py

@@ -0,0 +1,47 @@
+import psycopg
+from psycopg.conninfo import make_conninfo
+
+from upid import upid
+
+conninfo = make_conninfo(
+    host="localhost",
+    port=5432,
+    user="postgres",
+    password="mypassword",
+    dbname="postgres",
+)
+
+id_obj = upid("user")
+
+with psycopg.connect(conninfo) as conn:
+    create_ext = "CREATE EXTENSION IF NOT EXISTS upid_pg;"
+    conn.execute(create_ext)
+    print("Extension ready")
+
+    drop_table = "DROP TABLE IF EXISTS test_upid;"
+    conn.execute(drop_table)
+
+    create_table = """
+    CREATE TABLE test_upid (
+        id_upid upid NOT NULL,   -- pass a string
+        id_uuid uuid NOT NULL,   -- pass binary
+        id_text text NOT NULL    -- pass a string
+    );
+    """
+    conn.execute(create_table)
+    print("Table created")
+
+    query = """
+    INSERT INTO test_upid (id_upid, id_uuid, id_text)
+    VALUES (%s, %s, %s)
+    RETURNING *;
+    """
+    values = (
+        id_obj.to_str(),           # string for upid type
+        id_obj.to_uuid(),          # uuid for uuid type
+        id_obj.to_str(),           # string for text type
+    )
+
+    row = conn.execute(query, values).fetchone()
+    if row:
+        print(f"Inserted:\nid_upid={row[0]}\nid_uuid={row[1]}\nid_text={row[2]}")

examples/python/pyproject.toml

@@ -0,0 +1,20 @@
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+ignore-init-module-imports = true
+select = ["A", "E", "F", "I", "N", "Q", "U", "T100"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["upid"]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+include = ["py"]
+strict = ["py/**"]
+reportUnnecessaryTypeIgnoreComment = true
+reportUnusedCallResult = false
+pythonVersion = "3.9"
+pythonPlatform = "Linux"

examples/python/requirements.txt

@@ -0,0 +1,2 @@
+psycopg>=3
+upid

examples/rust/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "upid-example-rust"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+postgres = { version = "0.19", features = ["with-uuid-1"] }
+upid = { version = "0.2", features = ["uuid"] }
+uuid = "1.10.0"

examples/rust/README.md

@@ -0,0 +1,25 @@
+# example-python
+
+Clone this repo:
+```bash
+git clone [email protected]:carderne/upid.git
+cd upid/examples/rust
+```
+
+Get a Docker image running:
+```bash
+docker run --rm -e POSTGRES_PASSWORD=mypassword \
+  -p 5432:5432 --detach carderne/postgres-upid:16
+```
+
+Run the script:
+```bash
+cargo run
+
+# Extension ready
+# Table created
+# Inserted:
+# id_upid=user_2acqyewitnjij6oflrqzda
+# id_uuid=01916f2b-8ecc-dee7-928b-8dedf9d61576
+# id_text=user_2acqyewitnjij6oflrqzda
+```

examples/rust/src/main.rs

@@ -0,0 +1,49 @@
+use postgres::{Client, NoTls};
+use std::error::Error;
+use upid::Upid;
+use uuid::Uuid;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut client = Client::connect(
+        "host=localhost user=postgres password=mypassword dbname=postgres",
+        NoTls,
+    )?;
+
+    let create_ext = "CREATE EXTENSION IF NOT EXISTS upid_pg;";
+    client.execute(create_ext, &[])?;
+    println!("Extension ready");
+
+    let drop_table = "DROP TABLE IF EXISTS test_upid;";
+    client.execute(drop_table, &[])?;
+
+    let create_table = r#"
+        CREATE TABLE test_upid (
+            id_upid TEXT NOT NULL,   -- passing string for upid type
+            id_uuid UUID NOT NULL,   -- passing uuid for uuid type
+            id_text TEXT NOT NULL    -- passing string for text type
+        );
+    "#;
+    client.execute(create_table, &[])?;
+    println!("Table created");
+
+    let id = Upid::new("user");
+
+    let query = r#"
+        INSERT INTO test_upid (id_upid, id_uuid, id_text)
+        VALUES ($1, $2, $3)
+        RETURNING id_upid, id_uuid, id_text;
+    "#;
+    for row in client.query(
+        query,
+        &[&id.to_string(), &Uuid::from(id), &id.to_string()],
+    )? {
+        let id_upid: String = row.get(0);
+        let id_uuid: Uuid = row.get(1);
+        let id_text: String = row.get(2);
+        println!(
+            "Inserted:\nid_upid={id_upid}\nid_uuid={id_uuid}\nid_text={id_text}",
+        );
+    }
+
+    Ok(())
+}

py/upid/__init__.py

@@ -1,3 +1,3 @@
-__all__ = ["UPID", "upid"]
-
 from upid.core import UPID, upid
+
+__all__ = ["UPID", "upid"]

pyproject.toml

@@ -55,11 +55,12 @@ dev-dependencies = [
 ]
 
 [tool.ruff]
+include = ["py/**/*.py"]
+exclude = ["examples"]
 target-version = "py39"
 line-length = 120
 
 [tool.ruff.lint]
-ignore-init-module-imports = true
 select = ["A", "E", "F", "I", "N", "Q", "U", "T100"]
 
 [tool.ruff.lint.isort]