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:

.. code-block:: bash

   pip install tapestry-orm

Using uv
~~~~~~~~

If you're using `uv <https://docs.astral.sh/uv/>`_ (recommended for faster installs):

.. code-block:: bash

   uv add tapestry-orm

From Source
~~~~~~~~~~~

To install the development version from source:

.. code-block:: bash

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

Or with uv:

.. code-block:: bash

   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:

.. code-block:: bash

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

Using Package Managers
~~~~~~~~~~~~~~~~~~~~~~

**macOS (Homebrew):**

.. code-block:: bash

   brew install surrealdb/tap/surreal

**Linux:**

.. code-block:: bash

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

**Windows (PowerShell):**

.. code-block:: powershell

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

For more installation options, see the `SurrealDB installation guide <https://surrealdb.com/install>`_.

Development Installation
------------------------

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

.. code-block:: bash

   # 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:

.. code-block:: python

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

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

.. code-block:: python

   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 :doc:`quickstart` 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+:

.. code-block:: bash

   python --version
   pip show tapestry-orm

**Connection Issues**

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

.. code-block:: bash

   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:

.. code-block:: bash

   # 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