spanish-tools 0.1.0

Intelligent data processing tools for Spanish datasets (encoding, dates, numbers).

Spanish Tools

Spanish Tools is a Python library specifically designed to simplify the analysis and processing of Spanish language data. It efficiently handles common issues such as encoding, regional numeric formats (decimal comma), dates, and text normalization (accents, 'ñ').

🚀 Installation

Standard Installation (PyPI)

pip install spanish_tools

Installation in Google Colab

To install the latest development version directly from GitHub:

!pip install spanish_tools

Note: If you are using the CSV loading functions (spanish_tools.core), ensure pandas is installed (included by default in Colab and Anaconda).

⚡ Quick Start

"Pandas-style" loading and cleaning in two simple steps:

import spanish_tools as spa

# 1. Load Data (Universal: CSV, Excel, etc.)
# This works for .csv, .xls, and .xlsx automatically.
# - Sets Spanish defaults (dec=',', sep=';') for CSVs.
# - Cleans headers to snake_case.
# - Fixes encoding (mojibake) in all text columns.
df = spa.load_data("sales_2024.xlsx")

# You can still pass pandas arguments:
df_csv = spa.load_data(
    "sales_old.csv", 
    encoding="latin1", 
    parse_dates=["fecha"]
)

# 2. Clean Text (Explicit)
# This will clean the content of specific columns (removes accents, standardizes spaces, lowercases)
df = spa.clean_text(df, fields=["comments", "city"])

# 3. Clean Text (All)
# Or clean the entire DataFrame
df = spa.clean_text(df, fields="all", remove_accents=True)

print(df.head())
# Columns: 'fecha', 'ciudad' (snake_case headers)
# Content: 'malaga' (clean text)

✨ Key Features

• Universal Loader: load_data handles CSV and Excel files seamlessly.
• Auto-Cleaning: Automatically fixes mojibake (encoding errors) and normalizes headers upon loading.
• "Pandas-Native" UX: Intuitive functions that integrate naturally into your workflow.

📚 API Reference

1. Loading and Processing (spanish_tools.core)

spa.load_data

Universal loader for CSV, Excel, ODS, XML, and Clipboard. Wraps pandas and applies automatic Spanish-focused cleaning.

def load_data(
    ruta_archivo: str,
    separador: str = ';',
    **kwargs
) -> Optional[pd.DataFrame]

Supported Formats:

• CSV (.csv): Auto-configured for Spanish standards (;, ,).
• Excel (.xls, .xlsx): Standard Excel files.
• OpenDocument (.ods): Common in Public Administration.
• XML (.xml): Generic XML parsing.
• Clipboard: Use spa.load_data("clipboard") to load copied data.

Useful Pandas Arguments (**kwargs)

You can customize the loading by passing any standard pandas arguments:

Argument	Description	Example
sheet_name	(Excel/ODS) specific sheet to load.	sheet_name='DataV1'
encoding	(CSV) Fixes strange characters.	encoding='latin1'
parse_dates	Automatically converts columns to datetime.	parse_dates=['date']
dtype	Forces data type.	dtype={'dni': str}

---

spa.clean_text

Cleans the text content of a loaded DataFrame.

def clean_text(
    df: pd.DataFrame, 
    fields: List[str] | str,
    remove_accents: bool = True,
    **kwargs
) -> pd.DataFrame

• fields: Columns to clean. Can be a list of names ['col_a'] or "all" for the entire DataFrame.
• remove_accents: If True (default), removes accents ('á' -> 'a') and normalizes 'ñ'.
• kwargs: Included for potential future extensions, currently ignored.

2. Normalization

clean_header

Converts text to snake_case format, ideal for variable or column names.

import spanish_tools as spa

print(spa.clean_header("Creation Year (2024)"))
# Output: "creation_year_2024"

3. Text Cleaning

clean_string

Atomic cleaning for a text string. Removes unnecessary punctuation, extra spaces, and optionally accents.

import spanish_tools as spa

text = "  HELLO   WORLD! "
print(spa.clean_string(text))
# Output: "hello world"

🤝 Contributing

Contributions are welcome! If you find a bug or have an idea for a new feature:

1. Fork the repository.
2. Create a branch for your feature (git checkout -b feature/new-feature).
3. Commit your changes (git commit -m 'Add new feature').
4. Push to the branch (git push origin feature/new-feature).
5. Open a Pull Request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.