Metadata-Version: 2.4
Name: megabyte
Version: 0.0.0
Summary: ASCII text encoder/decoder Python library
Project-URL: Homepage, https://github.com/vlad-technology/megabyte
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

## **Megabyte**
#### Megabyte - library for decoding, encoding files, texts, etc.

#### With megabyte you may:
* Fast encode datasets
* Fast decode answering
* Decode binary files to a normal view
* Prepare text/numeric data for training an ML regressor

## Installation
```bash
pip install megabyte
```

### GitHub / Source
https://github.com/vlad-technology/megabyte

---

## Fast start

```python
from megabyte import (
    anytotextbytes,
    anytotextlatin,
    textencoder_ascii,
    textdecoder_ascii,
    fileencoder_ascii,
    fileencoder_ascii_latin1,
    filedecoder_ascii,
)
```

### `anytotextbytes(path) -> str`
Reads a binary file and returns its raw Python `bytes` representation as a string.

```python
path1 = "YOUR_BINARY_FILE_PATH"
print(anytotextbytes(path1))
```

### `anytotextlatin(path) -> str`
Reads a binary file and decodes it using `latin-1`, so every byte (0-255) maps to exactly one character with no data loss. Recommended for encoding arbitrary binary files (images, executables, archives, etc.).

```python
path1 = "YOUR_BINARY_FILE_PATH"
print(anytotextlatin(path1))
```

### `textencoder_ascii(text) -> str`
Encodes a string of ASCII characters (codes 0-127) into a numeric string representation.

```python
text = "YOUR_TEXT"
print(textencoder_ascii(text))
```

### `textdecoder_ascii(numbers) -> str`
Decodes a numeric string (produced by `textencoder_ascii`) back into the original text.

```python
numbers = "YOUR_NUMBERS"
print(textdecoder_ascii(numbers))
```

### `fileencoder_ascii(path) -> bool`
Encodes any file into a `.txt` file containing its ASCII-numeric representation.

```python
if fileencoder_ascii("YOUR_FILE_PATH") == True:
    print("Successfully encoded")
else:
    print("Bad file")
```

### `fileencoder_ascii_latin1(path) -> bool`
Same as `fileencoder_ascii`, but reads the source file through `latin-1` decoding first — recommended for binary files, since it preserves every byte without loss.

```python
if fileencoder_ascii_latin1("YOUR_FILE_PATH") == True:
    print("Successfully encoded")
else:
    print("Bad file")
```

### `filedecoder_ascii(path) -> bool`
Decodes a `.txt` file (previously produced by `fileencoder_ascii` / `fileencoder_ascii_latin1`) back into its original numeric-to-text form.

```python
if filedecoder_ascii("YOUR_ENCODED_FILE_PATH.txt") == True:
    print("Successfully decoded")
else:
    print("Bad file")
```

---

## Notes
* Only characters with ASCII codes `0-127` are encoded; bytes outside this range (128-255) are skipped.
* For binary files, prefer `fileencoder_ascii_latin1` over `fileencoder_ascii` — it avoids corrupting the byte stream during the read step.
* Output files are written with `.txt` appended to the original filename (e.g. `image.png` → `image.png.txt`).

## License
MIT
