Metadata-Version: 2.1
Name: robot_hat
Version: 1.5.5
Summary: Custom version of Robot Hat Python library for Sunfounder's Raspberry Pi robots.
Author-email: Karim Aziiev <karim.aziiev@gmail.com>
License: GNU
Keywords: i2c,raspberrypi
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame
Requires-Dist: smbus2
Requires-Dist: gpiozero
Requires-Dist: RPi.GPIO
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"

# Robot Hat [![codecov](https://codecov.io/gh/KarimAziev/robot-hat/graph/badge.svg?token=2C863KHRLU)](https://codecov.io/gh/KarimAziev/robot-hat)

`robot_hat` is a custom Python library designed for the Raspberry Pi. It builds on and improves the original [Sunfounder Robot Hat Python library](https://github.com/sunfounder/robot-hat/tree/v2.0) by introducing significant enhancements, fixes, and improvements.

> **Note:** While not all modules are fully compatible with the original library, most of them are supported and can be used in similar ways.

## Key Features & Improvements

### 🚀 **No `sudo` Needed**

The original library includes several instances of unnecessary `sudo` usage. For example:

```python
User = os.popen('echo ${SUDO_USER:-$LOGNAME}').readline().strip()
UserHome = os.popen('getent passwd %s | cut -d: -f 6' % User).readline().strip()
config_file = '%s/.config/robot-hat/robot-hat.conf' % UserHome
```

This approach elevates permissions unnecessarily, even for reading the login name. All such patterns have been removed in this library.

### 🧹 **Type Hints & Clean Code**

This version prioritizes:

- **Type hints** for better developer experience.
- Modular, maintainable, and well-documented code.

### 🛠️ **Bug Fixes**

Numerous bugs from the original implementation have been identified and resolved.

### 🧩 **Mock Support for Testing**

Development and testing are now possible on non-Raspberry Pi platforms, thanks to the support of mocks. To enable mocking, set the following environment variables before importing the `robot_hat` library:

```python
import os
os.environ["GPIOZERO_PIN_FACTORY"] = "mock"
os.environ["PYGAME_HIDE_SUPPORT_PROMPT"] = "1"
```

---

## 🔧 Installation

You can install the `robot_hat` library in multiple ways based on your requirements:

### Option 1: Install the Latest Version from GitHub

To install the latest version directly from the `main` branch:

```bash
pip install git+https://github.com/KarimAziev/robot-hat.git@main#egg=robot_hat
```

#### Using in `requirements.txt`

Add the following line to your `requirements.txt` file:

```plaintext
git+https://github.com/KarimAziev/robot-hat.git@main#egg=robot_hat
```

---

### Option 2: Install a Specific Version

To install a specific version (e.g., `v1.0.1`), reference a Git tag:

```bash
pip install git+https://github.com/KarimAziev/robot-hat.git@v1.0.1#egg=robot_hat
```

#### Using in `requirements.txt`

To lock your installation to that specific version:

```plaintext
git+https://github.com/KarimAziev/robot-hat.git@v1.0.1#egg=robot_hat
```

---

### Option 3: Install a Specific Commit

To install the library from a specific Git commit (replace `<commit_hash>` with the desired commit hash):

```bash
pip install git+https://github.com/KarimAziev/robot-hat.git@<commit_hash>#egg=robot_hat
```

#### Using in `requirements.txt`

Specify the commit hash like this:

```plaintext
git+https://github.com/KarimAziev/robot-hat.git@a1b2c3d4#egg=robot_hat
```

---

### Option 4: Install with Development Dependencies

The library includes optional development dependencies (e.g., for linting, testing). To install them:

```bash
pip install "robot_hat[dev]"
```

If installing from GitHub:

```bash
pip install git+https://github.com/KarimAziev/robot-hat.git@main#egg=robot_hat[dev]
```

#### Using in `requirements.txt`

```plaintext
git+https://github.com/KarimAziev/robot-hat.git@main#egg=robot_hat[dev]
```

---

### Verifying the Installation

After installing, verify the library is set up correctly by running:

```bash
python -c "import robot_hat; print(robot_hat.version)"
```

This will display the installed version of `robot_hat`. If `setuptools_scm` is being used, the version reflects the Git tags or branch state.

---

## 🚀 Development Environment Setup

### Prerequisites

1. **Python 3.10 or newer** must be installed.
2. Ensure you have `pip` installed (a recent version is recommended):
   ```bash
   python3 -m pip install --upgrade pip
   ```

### Steps to Set Up

1. **Clone the Repository**:

   ```bash
   git clone https://github.com/KarimAziev/robot-hat.git
   cd robot-hat
   ```

2. **Set Up a Virtual Environment**:

   ```bash
   python3 -m venv .venv
   source .venv/bin/activate  # Linux/Mac
   # OR
   .venv\Scripts\activate     # Windows
   ```

3. **Upgrade Core Tools**:

   ```bash
   pip install --upgrade pip setuptools wheel
   ```

4. **Install in Development Mode**:
   ```bash
   pip install -e ".[dev]"  # Installs all dev dependencies (e.g., black, isort, pre-commit)
   ```

---

## 📦 Distribution

To create distributable artifacts (e.g., `.tar.gz` and `.whl` files):

1. Install the build tool:

   ```bash
   pip install build
   ```

2. Build the project:
   ```bash
   python -m build
   ```
   The built files will be located in the `dist/` directory:

- Source distribution: `robot_hat-x.y.z.tar.gz`
- Wheel: `robot_hat-x.y.z-py3-none-any.whl`

These can be installed locally for testing or uploaded to PyPI for distribution.

---

## 🛠️ Common Commands

- **Clean Build Artifacts**:
  ```bash
  rm -rf build dist *.egg-info
  ```
- **Deactivate Virtual Environment**:
  ```bash
  deactivate
  ```

---

## ⚡ Notes & Recommendations

- The library uses `setuptools_scm` for versioning, which dynamically determines the version based on Git tags. Use proper semantic versioning (e.g., `v1.0.0`) in your repository for best results.
- Development tools like `black` (code formatter) and `isort` (import sorter) are automatically installed with `[dev]` dependencies.
