Installation

This guide will help you install Tapestry and set up your development environment.

Requirements

Before installing Tapestry, ensure you have the following:

Python 3.12 or higher
SurrealDB 1.0 or higher
A package manager (pip or uv)

Installing Tapestry

Using pip

The simplest way to install Tapestry is using pip:

pip install tapestry-orm

Using uv

If you’re using uv (recommended for faster installs):

uv add tapestry-orm

From Source

To install the development version from source:

git clone https://github.com/yourusername/tapestry-orm.git
cd tapestry-orm
pip install -e .

Or with uv:

git clone https://github.com/yourusername/tapestry-orm.git
cd tapestry-orm
uv sync

Installing SurrealDB

Tapestry requires a running SurrealDB instance. Here are several ways to install it:

Using Docker

The easiest way to run SurrealDB is using Docker:

docker run --rm --pull always -p 8000:8000 \
  surrealdb/surrealdb:latest start \
  --log trace --user root --pass root

Using Package Managers

macOS (Homebrew):

brew install surrealdb/tap/surreal

Linux:

curl -sSf https://install.surrealdb.com | sh

Windows (PowerShell):

iwr https://windows.surrealdb.com -useb | iex

For more installation options, see the SurrealDB installation guide.

Development Installation

If you plan to contribute to Tapestry or want to run tests, install the development dependencies:

# Using pip
pip install tapestry-orm[dev]

# Using uv
uv sync --all-groups

This will install additional tools including:

pytest for testing
mypy and pyright for type checking
sphinx for documentation
And other development tools

Verifying Installation

To verify that Tapestry is installed correctly, open a Python interpreter and try:

>>> import tapestry
>>> print(tapestry.__version__)
0.0.1

You can also verify SurrealDB is running by connecting to it:

from surrealdb import Surreal

async def test_connection():
    async with Surreal("ws://localhost:8000/rpc") as db:
        await db.signin({"user": "root", "pass": "root"})
        await db.use("test", "test")
        print("Connected to SurrealDB!")

# Run with: python -m asyncio
import asyncio
asyncio.run(test_connection())

Next Steps

Now that you have Tapestry installed, check out the Quickstart Guide guide to learn how to use it!

Troubleshooting

Import Error

If you get an import error, make sure you installed the package correctly and that you’re using Python 3.12+:

python --version
pip show tapestry-orm

Connection Issues

If you can’t connect to SurrealDB, verify it’s running:

curl http://localhost:8000/health

You should get a response indicating the server is running.

Version Conflicts

If you experience dependency conflicts, try using a virtual environment:

# Using venv
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install tapestry-orm

# Using uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync