Metadata-Version: 2.4
Name: pyarcscripts
Version: 0.0.12
Summary: Boîte à outils partagée pour la famille de packages pyarc*.
Home-page: https://github.com/inicode/pyarc-utilities
Author: INICODE
Author-email: contact.inicode@gmail.com
License: MIT
Keywords: python,inicode,pyarcscripts,utilities,aes,semver,logging,filesystem
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
Requires-Dist: pycryptodome>=3.15
Requires-Dist: packaging>=21.0
Requires-Dist: pytz>=2022.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: summary

# pyarcscripts

**Boîte à outils partagée** de la famille `pyarc*`.

`pyarcscripts` regroupe les utilitaires transversaux utilisés par les autres
packages `pyarc*` : manipulation de chaînes, filesystem, logging, chiffrement
AES, gestion des versions semver et exceptions localisées (fr/en).

Conçu et maintenu par **INICODE**.

---

## Table des matières

1. [Installation](#installation)
2. [Modules et fonctionnalités](#modules-et-fonctionnalités)
3. [Exemples d'utilisation](#exemples-dutilisation)
4. [API de référence](#api-de-référence)
5. [Architecture](#architecture)
6. [Auteur](#auteur)

---

## Installation

```bash
pip install pyarcscripts
```

### Dépendances

| Package | Utilisation |
|---------|-------------|
| `pycryptodome` | Chiffrement AES (`pyarcscripts.AESEncryptor`). |
| `packaging` | Vérification de versions semver. |
| `pytz` | Fuseaux horaires (UTC). |

Ces dépendances sont installées automatiquement par `pip`.

### Installation en mode développeur

```bash
git clone https://github.com/inicode/pyarc-utilities.git
cd pyarc-utilities
python cmd.py --build --only pyarcscripts
pip install dist/pyarcscripts-*.whl
```

---

## Modules et fonctionnalités

| Module | Rôle |
|--------|------|
| `config.py` | Constantes globales : environnement (`NODEENV`), `DEBUG`, formats date/heure, langues supportées. |
| `string.py` | Manipulation de chaînes : `ucFirst`, `Lower`, `Upper`, `Capitalize`, `RandomStr`, `CleanName`. |
| `file.py` | Helpers filesystem : création/suppression de fichiers/dossiers, jointure de chemins, noms de logs. |
| `logger.py` | Logger préconfiguré avec rotation et archivage. |
| `utils.py` | Détection de langue, parcours récursif de données (`loopData`, `loopData2`). |
| `encryption.py` | Chiffrement AES-CBC avec clés aléatoires ou dérivées PBKDF2. |
| `versionning.py` | Vérification de versions semver (`^`, `~`, `||`, `&&`, intervalles). |
| `exception.py` | Hiérarchie d'exceptions localisées (fr/en). |

---

## Exemples d'utilisation

### Chaînes de caractères

```python
from pyarcscripts import (
    ucFirst, Lower, Upper, Capitalize, RandomStr, CleanName
)

# Capitaliser la première lettre
ucFirst("hello")  # "Hello"

# Majuscules / minuscules
Upper("hello")    # "HELLO"
Lower("WORLD")    # "world"

# Nettoyer un nom de fichier / identifiant
CleanName("Mon Fichier @spécial!.txt")
# -> "Mon_Fichier_sp_cial_txt"

# Générer un token aléatoire
token = RandomStr(typeStr='alphanumeric', lengthStr=32)
```

### Fichiers et dossiers

```python
from pyarcscripts import createFile, createFolder, removeFile, pathsJoin

# Créer un dossier (récursif)
createFolder("output/data")

# Créer un fichier avec contenu
createFile("output/data/result.txt", content="hello world")

# Jointure portable de chemins
pathsJoin("output", "data", "result.txt")
```

### Logging

```python
from pyarcscripts import GetLogger

logger = GetLogger("monapp", logsFolder="logs")
logger.info("Démarrage de l'application")
logger.error("Une erreur est survenue")
```

### Chiffrement AES

```python
from pyarcscripts import AESEncryptor

aes = AESEncryptor(key_size=256)

# Clé aléatoire
key = aes.generate_key()

# Chiffrer / déchiffrer
encrypted = aes.encrypt("message secret", key)
decrypted = aes.decrypt(
    encrypted["ciphertext"],
    key,
    encrypted["iv"]
)

# Clé dérivée d'un mot de passe (PBKDF2)
key, salt = aes.generate_secure_fixed_key(
    "mon-mot-de-passe",
    iterations=100000
)
```

### Vérification de versions

```python
from pyarcscripts import check_version

# Opérateurs classiques
check_version("1.2.3", ">=1.0.0")
check_version("1.2.3", ">=1.0,<2.0")

# Opérateurs semver avancés
check_version("1.2.3", "^1.0.0")
check_version("1.2.3", "~1.2.0")
check_version("1.2.3", ">=1.0.0 || 2.5.0")
```

### Parcours récursif de données

```python
from pyarcscripts import loopData

def uppercase_values(res, data, parents, parent):
    if isinstance(data, str):
        return data.upper()
    return res

result = loopData(
    {"a": "hello", "b": ["world"]},
    mapFnc=uppercase_values
)
# -> {'a': 'HELLO', 'b': ['WORLD']}
```

### Détection de langue

```python
from pyarcscripts import getLang, getLangCode

lang = getLang("fr")
code = getLangCode("fr")  # ex. "fr_FR"
```

---

## API de référence

### Chaînes

```python
from pyarcscripts import (
    ucFirst, Lower, Upper, Capitalize, RandomStr, CleanName
)
```

### Fichiers

```python
from pyarcscripts import (
    createPath, createFile, createFolder,
    removeFile, removeFolder, removeFileAndFolder,
    pathsJoin, cleanFilenameWithoutExtension,
    createlogFilename, removeEmptyFiles
)
```

### Logging

```python
from pyarcscripts import GetLogger, LoggerArchive, createfolderLogger
```

### Chiffrement

```python
from pyarcscripts import AESEncryptor, BinaryEncode
```

### Versions

```python
from pyarcscripts import check_version
```

### Exceptions

```python
from pyarcscripts import Error, InternalError, EncryptionError
```

### Constantes publiques

```python
from pyarcscripts import NODEENV, DEBUG
from pyarcscripts import (
    tabNumerique, tabAlphabetique, tabAlphanumerique
)
from pyarcscripts import (
    dateTimeFormatInitial,
    dateFormatInitial,
    timeFormatInitial
)
```

---

## Architecture

```text
pyarcscripts/
├── __init__.py        # API publique
├── config.py          # Constantes globales
├── string.py          # Manipulation de chaînes
├── file.py            # Helpers filesystem
├── logger.py          # Logging avec rotation
├── utils.py           # Utilitaires génériques
├── encryption.py      # Chiffrement AES
├── versionning.py     # Vérification semver
└── exception.py       # Exceptions localisées
```

---

## Auteur

Développé avec passion par **INICODE** — `contact.inicode@gmail.com`.

Licence : MIT.
