TITLE: Setup Development Environment with uv
DESCRIPTION: Provides a quick setup guide for the SafeText development environment using `uv`, including cloning the repository, running platform-specific setup scripts, and manual installation steps. It also covers initial test execution and code style fixes.
SOURCE: https://github.com/viddexa/safetext/blob/main/CONTRIBUTING.md#_snippet_0

LANGUAGE: Shell
CODE:
```
# quick setup
git clone https://github.com/viddexa/safetext.git
cd safetext

# Unix/Linux/macOS
./scripts/setup.sh            # installs uv and dependencies
./scripts/run_tests.sh        # run tests

# Windows
scripts\setup.bat             # checks uv and installs dependencies  
scripts\run_tests.bat         # run tests

# or manual setup (all platforms)
# install uv from https://github.com/astral-sh/uv
uv sync --extra dev

# run tests (after setup, the venv is activated automatically)
./scripts/run_tests.sh        # Unix/Linux/macOS  
scripts\run_tests.bat         # Windows

# or manually
source .venv/bin/activate     # Unix/Linux/macOS
# or
.venv\Scripts\activate        # Windows
pytest -n auto

# before committing - fix code style issues
ruff check --fix .
ruff format .
```

----------------------------------------

TITLE: Run SafeText Tests with Scripts
DESCRIPTION: Provides examples of using the `run_tests.sh` (Unix/Linux/macOS) and `run_tests.bat` (Windows) scripts with various arguments to perform quick tests, full tests, generate coverage reports, run linting checks, or execute all checks.
SOURCE: https://github.com/viddexa/safetext/blob/main/CONTRIBUTING.md#_snippet_3

LANGUAGE: Shell
CODE:
```
# Unix/Linux/macOS
./scripts/run_tests.sh quick     # fast tests only (default)
./scripts/run_tests.sh full      # all tests including slow ones
./scripts/run_tests.sh coverage  # generate coverage report
./scripts/run_tests.sh lint      # run only linting checks
./scripts/run_tests.sh all       # linting + all tests

# Windows
scripts\run_tests.bat quick      # same options as above
scripts\run_tests.bat full
scripts\run_tests.bat coverage
scripts\run_tests.bat lint
scripts\run_tests.bat all
```

----------------------------------------

TITLE: SafeText Class API Reference
DESCRIPTION: The `SafeText` class provides functionalities for profanity detection, censoring, and automated language detection. It can be initialized with a specific language or configured to detect language from text or SRT files, and supports whitelisting to exclude specific terms.
SOURCE: https://github.com/viddexa/safetext/blob/main/README.md#_snippet_5

LANGUAGE: APIDOC
CODE:
```
class SafeText:
  __init__(self, language: str = None, whitelist: list[str] | str = None)
    language: str | None
      The language code (e.g., 'en', 'tr') for profanity detection. If None, language can be detected automatically.
    whitelist: list[str] | str | None
      A list of words to exclude from profanity detection, or a path to a file containing one word per line.

  check_profanity(self, text: str) -> dict | None
    text: str
      The input text to check for profanity.
    Returns: dict | None
      A dictionary containing 'word', 'index', 'start', and 'end' if profanity is found, otherwise None.

  censor_profanity(self, text: str) -> str
    text: str
      The input text in which to censor profanity.
    Returns: str
      The text with detected profanity replaced by asterisks.

  set_language_from_text(self, text: str) -> None
    text: str
      The text from which to detect the language.
    Sets: self.language
      Updates the instance's language attribute based on the detected language.

  set_language_from_srt(self, srt_file_path: str) -> None
    srt_file_path: str
      The path to the SRT file from which to detect the language.
    Sets: self.language
      Updates the instance's language attribute based on the detected language from the SRT file.
```

----------------------------------------

TITLE: Install safetext Python package using pip
DESCRIPTION: This snippet shows how to install the safetext library using pip, the Python package installer. This is the standard way to get the library set up for use in your projects, ensuring all dependencies are met.
SOURCE: https://github.com/viddexa/safetext/blob/main/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
pip install safetext
```

----------------------------------------

TITLE: Quick Start: Initial Setup and Test Execution on Windows
DESCRIPTION: This snippet provides the necessary commands to quickly set up the development environment and run tests on Windows. It covers the initial setup script which checks for `uv` and installs dependencies, and the test runner script with options for quick tests or detailed help.
SOURCE: https://github.com/viddexa/safetext/blob/main/scripts/README.md#_snippet_1

LANGUAGE: batch
CODE:
```
# initial setup (checks uv and installs dependencies)
scripts\setup.bat

# run tests (various options available)
scripts\run_tests.bat          # runs quick tests by default
scripts\run_tests.bat help     # see all options
```

----------------------------------------

TITLE: Check and censor profanity in text using SafeText (Python)
DESCRIPTION: This example demonstrates how to initialize SafeText for a specific language, check for profanity in a given text, and then censor the detected profanity. The `check_profanity` method returns details about the detected word, while `censor_profanity` replaces it with asterisks.
SOURCE: https://github.com/viddexa/safetext/blob/main/README.md#_snippet_1

LANGUAGE: python
CODE:
```
from safetext import SafeText

st = SafeText(language='en')

results = st.check_profanity(text='Some text with <profanity-word>.')
# {'word': '<profanity-word>', 'index': 4, 'start': 15, 'end': 31}

text = st.censor_profanity(text='Some text with <profanity-word>.')
# "Some text with ***."
```

----------------------------------------

TITLE: Quick Start: Initial Setup and Test Execution on Unix/Linux/macOS
DESCRIPTION: This snippet provides the necessary commands to quickly set up the development environment and run tests on Unix, Linux, or macOS. It covers the initial setup script which installs `uv` and dependencies, and the test runner script with options for quick tests or detailed help.
SOURCE: https://github.com/viddexa/safetext/blob/main/scripts/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
# initial setup (installs uv and dependencies)
./scripts/setup.sh

# run tests (various options available)
./scripts/run_tests.sh         # runs quick tests by default
./scripts/run_tests.sh help    # see all options
```

----------------------------------------

TITLE: Quick Start: Running SafeText Tests with uv and Pytest
DESCRIPTION: Instructions for setting up the development environment and running the SafeText test suite. Covers initial setup with `uv`, activating the virtual environment, running all tests in parallel, skipping slow tests, executing specific test files, and generating coverage reports.
SOURCE: https://github.com/viddexa/safetext/blob/main/tests/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
# first time setup
uv sync --extra dev

# activate virtual environment
source .venv/bin/activate  # unix/linux/macos
# or
.venv\Scripts\activate      # windows

# run all tests in parallel
pytest -n auto

# run only fast tests (skip slow/performance tests)
pytest -m "not slow"

# run specific test file
pytest tests/test_basic.py

# run with coverage
pytest --cov=safetext --cov-report=html
```

----------------------------------------

TITLE: Detect language from text using SafeText (Python)
DESCRIPTION: This example shows how to automatically detect the language of a given text using SafeText. By initializing SafeText without a language and then calling `set_language_from_text`, the library can infer the language, which is then accessible via the `language` attribute.
SOURCE: https://github.com/viddexa/safetext/blob/main/README.md#_snippet_3

LANGUAGE: python
CODE:
```
from safetext import SafeText

eng_text = "This story is about to take a dark turn."

st = SafeText(language=None)
st.set_language_from_text(eng_text)

# st.language will be 'en'
```

----------------------------------------

TITLE: Setup Development Environment with pip
DESCRIPTION: Outlines the traditional development setup process using `pip`, including cloning the repository, creating and activating a virtual environment, installing development dependencies, and running tests with parallel execution. It also includes commands for code style fixes.
SOURCE: https://github.com/viddexa/safetext/blob/main/CONTRIBUTING.md#_snippet_2

LANGUAGE: Shell
CODE:
```
# clone and setup
git clone https://github.com/viddexa/safetext.git
cd safetext

# create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# install
pip install -e ".[dev]"

# run tests with parallel execution
pytest -n auto

# before committing
ruff check --fix . && ruff format .
```

----------------------------------------

TITLE: Configure SafeText with a custom whitelist (Python)
DESCRIPTION: This snippet illustrates how to initialize the SafeText object with a whitelist to exclude specific words from profanity detection. The whitelist can be provided as a list of strings directly or by specifying a path to a text file containing one word per line.
SOURCE: https://github.com/viddexa/safetext/blob/main/README.md#_snippet_2

LANGUAGE: python
CODE:
```
# Using a list of words
st = SafeText(language='en', whitelist=['word1', 'word2'])

# Using a file (one word per line)
st = SafeText(language='en', whitelist='path/to/whitelist.txt')
```

----------------------------------------

TITLE: Activate Virtual Environment for uv
DESCRIPTION: Demonstrates how to activate the virtual environment created by `uv` on both Unix/Linux/macOS and Windows, which is crucial before running Python commands like `pytest`.
SOURCE: https://github.com/viddexa/safetext/blob/main/CONTRIBUTING.md#_snippet_1

LANGUAGE: Shell
CODE:
```
source .venv/bin/activate  # Unix/Linux/macOS
.venv\Scripts\activate     # Windows
```

----------------------------------------

TITLE: Troubleshooting: Making Scripts Executable on Unix/Linux/macOS
DESCRIPTION: This command resolves 'command not found' errors for shell scripts on Unix, Linux, or macOS. It grants execute permissions to all `.sh` files within the `scripts/` directory, ensuring they can be run directly.
SOURCE: https://github.com/viddexa/safetext/blob/main/scripts/README.md#_snippet_3

LANGUAGE: bash
CODE:
```
# make scripts executable
chmod +x scripts/*.sh
```

----------------------------------------

TITLE: Troubleshooting: Manually Managing Virtual Environments
DESCRIPTION: This snippet provides commands for manually creating or synchronizing a Python virtual environment using `uv` and then activating it. It includes separate activation commands tailored for Unix/Linux/macOS and Windows operating systems, useful for resolving virtual environment issues.
SOURCE: https://github.com/viddexa/safetext/blob/main/scripts/README.md#_snippet_4

LANGUAGE: bash
CODE:
```
# manually create/activate environment
uv sync --extra dev
source .venv/bin/activate  # unix/linux/macos
```

LANGUAGE: batch
CODE:
```
# manually create/activate environment
uv sync --extra dev
.venv\Scripts\activate     # windows
```

----------------------------------------

TITLE: Test Runner: Executing Specific Test Modes
DESCRIPTION: This section demonstrates how to use the `run_tests.sh` script to execute tests in various predefined modes. Each command targets a specific testing scenario, such as quick parallel tests, full test suite, coverage reporting, sequential execution, linting, or a complete suite including linting and all tests.
SOURCE: https://github.com/viddexa/safetext/blob/main/scripts/README.md#_snippet_2

LANGUAGE: bash
CODE:
```
./scripts/run_tests.sh quick
```

LANGUAGE: bash
CODE:
```
./scripts/run_tests.sh full
```

LANGUAGE: bash
CODE:
```
./scripts/run_tests.sh coverage
```

LANGUAGE: bash
CODE:
```
./scripts/run_tests.sh single
```

LANGUAGE: bash
CODE:
```
./scripts/run_tests.sh lint
```

LANGUAGE: bash
CODE:
```
./scripts/run_tests.sh all
```

----------------------------------------

TITLE: Pytest Command Line Arguments for Test Execution
DESCRIPTION: A collection of useful `pytest` command-line arguments for controlling test execution. Includes options for parallel execution (`-n auto`), skipping performance tests (`-m "not slow"`), verbose output (`-v`), running only the last failed tests (`--lf`), and running specific tests by name pattern (`-k "test_name"`).
SOURCE: https://github.com/viddexa/safetext/blob/main/tests/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
-n auto
```

LANGUAGE: bash
CODE:
```
-m "not slow"
```

LANGUAGE: bash
CODE:
```
-v
```

LANGUAGE: bash
CODE:
```
--lf
```

LANGUAGE: bash
CODE:
```
-k "test_name"
```

----------------------------------------

TITLE: Detect language from SRT file using SafeText (Python)
DESCRIPTION: This snippet demonstrates how SafeText can automatically detect the language from an SRT (subtitle) file. Initialize SafeText without a language and use `set_language_from_srt` with the file path to infer the language, which is then stored in the `language` attribute.
SOURCE: https://github.com/viddexa/safetext/blob/main/README.md#_snippet_4

LANGUAGE: python
CODE:
```
from safetext import SafeText

turkish_srt_file_path = "turkish.srt"

st = SafeText(language=None)
st.set_language_from_srt(turkish_srt_file_path)

# st.language will be 'tr'
```