# ACFortFormat
Fortran-style reading and writing utility in Python.
Support for fixed formats, free reading, type inference, and formatted output.<br>
A powerful and flexible Python library for handling data input/output (I/O) operations, inspired by Fortran's formatting syntax and also supporting native Python-style I/O operations.
`acfortformat` is ideal for engineers, scientists, and developers working with data generated or consumed by Fortran applications, or for those who simply need precise control over data formatting in their Python applications.
## Features
* **Fortran-Style Reading and Writing:** Full support for the Fortran formatting language (FORMAT), allowing you to specify field width, data type (integer, real, string), and position control (T, X, etc.).
* **Fixed and Free Formatting:** Handles both fixed formats (predefined columns) and free formats (space- or comma-separated, with handling of quoted strings).
* **Type Inferring:** Automatically detects the data type (integer, float, string) when reading in free format.
* **Easy Integration:** Designed to be easy to integrate into any Python project.
* **Format Cache:** Performance optimization by reusing pre-compiled format descriptors.
* **Versatile Output:** Writes data to the console or any file-like object.
---
## Installation
You can automatically install ACFortFormat by running:
```bash
pip install acfortformat
```
> Requires an internet connection, `pip` available, and Python ≥ 3.7.
---
## Fortran-like I/O Utility – Key Features
### READING
`read(fp, fmt=None)` emulates the Fortran `READ` statement:
- `fmt=None` → behavior like `READ(*,*)` (free reading):
- Supports integers, floats (including `D` notation), and strings.
- Strings enclosed in double or single quotes are treated as a single value.
- Automatic type inference: `int`, `float`, `str`.
- `fmt="*"` → explicit equivalent of `READ(*,*)`.
- `fmt="(A)"` → reads the entire line as a single string.
- `fmt="(Fortran format)"` → Fixed-format reading (via `fortranformat`):
- Supports `I`, `F`, `A`, `X`, `Tn`, repetitions, etc.
- Supports fixed alignments, spacing, and columns.
- Uses *reader* caching for greater efficiency.
---
### WRITING
`write(data, fp=None, fmt=None, con=False)` emulates the Fortran `WRITE` instruction:
- `fmt=None` or `fmt="*"` → behavior like `WRITE(*,*)`:
- Elements of `data` (list or tuple) are printed separated by spaces.
- If `data` is a string or a simple number, it is printed directly.
- `fmt="(Fortran format)"` → fixed-format writing:
- Supports numeric precision (`F10.4`, `I4`, etc.), alignment, and embedded text.
- Supports complex formats.
- Uses *writers* cache for optimization.
---
\### ADDITIONAL UTILITIES
- `infer_type(s)` → converts string to `int`, `float`, or leaves it as `str`.
- `line_sanity(line)` → expands tabs to spaces for fixed reads.
- `EndOfFile` → custom end-of-file exception.
- Transparent file (`fp`) and console support (`con=True` in `write()`).
---
## Included Test Coverage
- Writing and reading with complex fixed formats.
- Reading/writing to files.
- Free format support (`*`), including text with spaces.
- Read-write symmetry validation.
---
## Usage
### Reading and Writing with Fortran Format
```python
from acfortformat import read, write, EndOfFile
# Define a Fortran format
fortran_fmt = "(I5,F10.3,A15)"
data_to_write = [12345, 67.8901, "Hello World"]
# Write to the console with Fortran format
print("--- Writing with Fortran format ---")
written_line = write(data_to_write, fmt=fortran_fmt)
print(f"Line written: '{written_line}'")
# Simulate reading from a string (which could be a file line)
print("\n--- Reading with Fortran format ---")
read_values = read(written_line, fmt=fortran_fmt)
print(f"Values read: {read_values}")
# Example of reading from a file
# Assuming 'data.txt' contains a line like: " 123 45.678 This is text"
# with the format "(I5, F7.3, A12)"
# with open("data.txt", "r") as f:
# values_from_file = read(f, fmt="(I5, F7.3, A12)")
# print(f"Values read from file: {values_from_file}")
```
### Free Format Reading and Writing (Python-like)
```python
from acfortformat import read, write, EndOfFile
# Free Format Data to Write
free_data = [10, 3.14, "a string with spaces", -50, "another 'string'"]
# Write to the console in free format
print("\n--- Free-Format Writing (*) ---")
free_written_line = write(free_data, fmt="*")
print(f"Line written: '{free_written_line}'")
# Reading from a free-form string
print("\n--- Free-Format Reading (*) ---")
free_read_values = read(free_written_line, fmt="*")
print(f"Read Values: {free_read_values}")
# Reading a quoted string for strings with spaces
quoted_line = '123 "string with spaces" 3.14 "another string with \'quotes\' and ""plus""" \'simple quote\''
print(f"\n--- Reading a quoted string in free-form ---")
parsed_quoted = read(quoted_line, fmt="*")
print(f"Parsed Values: {parsed_quoted}")
# Handling end of file
from io import StringIO
# Simulate a file with one line and then EOF
test_fp = StringIO("First line\n")
print("\n--- End of file handling ---")
print(f"Read: {read(test_fp, fmt='(A)')}")
# The second read will return the EndOfFile object
eof_result = read(test_fp, fmt='(A)')
if eof_result is EndOfFile:
print("End of file reached!")
```
---
## More Examples
For a broader range of practical use cases and detailed demonstrations of `acfortformat`'s features, explore the `examples/` directory in the project's GitHub repository. You'll find standalone scripts illustrating various scenarios like:
* **Simple Read/Write:** Basic Fortran-style and free-format I/O.
* **File I/O:** Reading and writing data directly to/from files.
* **Error Handling:** Demonstrating how to gracefully manage conditions like EndOfFile.
These examples are designed to be easily runnable and serve as a quick start for integrating `acfortformat` into your projects.
---
## Contributions
Contributions are welcome! If you find a bug or have an improvement, please open an issue or submit a pull request in the GitHub repository.
## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/acdeveloper-sci/acfortformat/blob/main/LICENSE) file for more details.
## Contact
If you have any questions or suggestions, please feel free to contact me at [ajcs.developer@gmail.com](mailto:ajcs.developer@gmail.com).
## Autor
**Adolph Cardozo**
📧 [ajcs.developer@gmail.com](mailto:ajcs.developer@gmail.com)
🔗 [GitHub](https://github.com/acdeveloper-sci)
Raw data
{
"_id": null,
"home_page": null,
"name": "acfortformat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "ACAI Engineering IA <acai.engineering.ia@gmail.com>",
"keywords": "fortran, io, format, read, write, scientific, data processing",
"author": null,
"author_email": "\"Adolph J. Cardozo S.\" <ajcs.developer@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/53/e7/e3f9b334a70a81d05394a0876f06be9da5129a171aadf9feb2a2647f8fe3/acfortformat-0.1.3.tar.gz",
"platform": null,
"description": "# ACFortFormat\r\n\r\nFortran-style reading and writing utility in Python.\r\nSupport for fixed formats, free reading, type inference, and formatted output.<br>\r\n\r\nA powerful and flexible Python library for handling data input/output (I/O) operations, inspired by Fortran's formatting syntax and also supporting native Python-style I/O operations.\r\n\r\n`acfortformat` is ideal for engineers, scientists, and developers working with data generated or consumed by Fortran applications, or for those who simply need precise control over data formatting in their Python applications.\r\n\r\n## Features\r\n\r\n* **Fortran-Style Reading and Writing:** Full support for the Fortran formatting language (FORMAT), allowing you to specify field width, data type (integer, real, string), and position control (T, X, etc.).\r\n* **Fixed and Free Formatting:** Handles both fixed formats (predefined columns) and free formats (space- or comma-separated, with handling of quoted strings).\r\n* **Type Inferring:** Automatically detects the data type (integer, float, string) when reading in free format.\r\n* **Easy Integration:** Designed to be easy to integrate into any Python project.\r\n* **Format Cache:** Performance optimization by reusing pre-compiled format descriptors.\r\n* **Versatile Output:** Writes data to the console or any file-like object.\r\n\r\n---\r\n\r\n## Installation\r\n\r\nYou can automatically install ACFortFormat by running:\r\n\r\n```bash\r\npip install acfortformat\r\n```\r\n> Requires an internet connection, `pip` available, and Python \u2265 3.7.\r\n\r\n---\r\n## Fortran-like I/O Utility \u2013 Key Features\r\n\r\n### READING\r\n\r\n`read(fp, fmt=None)` emulates the Fortran `READ` statement:\r\n\r\n- `fmt=None` \u2192 behavior like `READ(*,*)` (free reading):\r\n- Supports integers, floats (including `D` notation), and strings.\r\n- Strings enclosed in double or single quotes are treated as a single value.\r\n- Automatic type inference: `int`, `float`, `str`.\r\n\r\n- `fmt=\"*\"` \u2192 explicit equivalent of `READ(*,*)`.\r\n\r\n- `fmt=\"(A)\"` \u2192 reads the entire line as a single string.\r\n\r\n- `fmt=\"(Fortran format)\"` \u2192 Fixed-format reading (via `fortranformat`):\r\n- Supports `I`, `F`, `A`, `X`, `Tn`, repetitions, etc.\r\n- Supports fixed alignments, spacing, and columns.\r\n- Uses *reader* caching for greater efficiency.\r\n\r\n---\r\n\r\n### WRITING\r\n\r\n`write(data, fp=None, fmt=None, con=False)` emulates the Fortran `WRITE` instruction:\r\n\r\n- `fmt=None` or `fmt=\"*\"` \u2192 behavior like `WRITE(*,*)`:\r\n- Elements of `data` (list or tuple) are printed separated by spaces.\r\n- If `data` is a string or a simple number, it is printed directly.\r\n\r\n- `fmt=\"(Fortran format)\"` \u2192 fixed-format writing:\r\n- Supports numeric precision (`F10.4`, `I4`, etc.), alignment, and embedded text.\r\n- Supports complex formats.\r\n- Uses *writers* cache for optimization.\r\n\r\n---\r\n\r\n\\### ADDITIONAL UTILITIES\r\n\r\n- `infer_type(s)` \u2192 converts string to `int`, `float`, or leaves it as `str`.\r\n- `line_sanity(line)` \u2192 expands tabs to spaces for fixed reads.\r\n- `EndOfFile` \u2192 custom end-of-file exception.\r\n- Transparent file (`fp`) and console support (`con=True` in `write()`).\r\n\r\n---\r\n\r\n## Included Test Coverage\r\n\r\n- Writing and reading with complex fixed formats.\r\n- Reading/writing to files.\r\n- Free format support (`*`), including text with spaces.\r\n- Read-write symmetry validation.\r\n\r\n---\r\n\r\n## Usage\r\n\r\n### Reading and Writing with Fortran Format\r\n\r\n```python\r\nfrom acfortformat import read, write, EndOfFile\r\n\r\n# Define a Fortran format\r\nfortran_fmt = \"(I5,F10.3,A15)\"\r\ndata_to_write = [12345, 67.8901, \"Hello World\"]\r\n\r\n# Write to the console with Fortran format\r\nprint(\"--- Writing with Fortran format ---\")\r\nwritten_line = write(data_to_write, fmt=fortran_fmt)\r\nprint(f\"Line written: '{written_line}'\")\r\n\r\n# Simulate reading from a string (which could be a file line)\r\nprint(\"\\n--- Reading with Fortran format ---\")\r\nread_values = read(written_line, fmt=fortran_fmt)\r\nprint(f\"Values read: {read_values}\")\r\n\r\n# Example of reading from a file\r\n# Assuming 'data.txt' contains a line like: \" 123 45.678 This is text\"\r\n# with the format \"(I5, F7.3, A12)\"\r\n\r\n# with open(\"data.txt\", \"r\") as f:\r\n# values_from_file = read(f, fmt=\"(I5, F7.3, A12)\")\r\n# print(f\"Values read from file: {values_from_file}\")\r\n```\r\n\r\n### Free Format Reading and Writing (Python-like)\r\n\r\n```python\r\nfrom acfortformat import read, write, EndOfFile\r\n\r\n# Free Format Data to Write\r\nfree_data = [10, 3.14, \"a string with spaces\", -50, \"another 'string'\"]\r\n\r\n# Write to the console in free format\r\nprint(\"\\n--- Free-Format Writing (*) ---\")\r\nfree_written_line = write(free_data, fmt=\"*\")\r\nprint(f\"Line written: '{free_written_line}'\")\r\n\r\n# Reading from a free-form string\r\nprint(\"\\n--- Free-Format Reading (*) ---\")\r\nfree_read_values = read(free_written_line, fmt=\"*\")\r\nprint(f\"Read Values: {free_read_values}\")\r\n\r\n# Reading a quoted string for strings with spaces\r\nquoted_line = '123 \"string with spaces\" 3.14 \"another string with \\'quotes\\' and \"\"plus\"\"\" \\'simple quote\\''\r\nprint(f\"\\n--- Reading a quoted string in free-form ---\")\r\nparsed_quoted = read(quoted_line, fmt=\"*\")\r\nprint(f\"Parsed Values: {parsed_quoted}\")\r\n\r\n# Handling end of file\r\nfrom io import StringIO\r\n# Simulate a file with one line and then EOF\r\ntest_fp = StringIO(\"First line\\n\")\r\nprint(\"\\n--- End of file handling ---\")\r\nprint(f\"Read: {read(test_fp, fmt='(A)')}\")\r\n# The second read will return the EndOfFile object\r\neof_result = read(test_fp, fmt='(A)')\r\nif eof_result is EndOfFile:\r\n print(\"End of file reached!\")\r\n```\r\n\r\n---\r\n\r\n## More Examples\r\n\r\nFor a broader range of practical use cases and detailed demonstrations of `acfortformat`'s features, explore the `examples/` directory in the project's GitHub repository. You'll find standalone scripts illustrating various scenarios like:\r\n\r\n* **Simple Read/Write:** Basic Fortran-style and free-format I/O.\r\n* **File I/O:** Reading and writing data directly to/from files.\r\n* **Error Handling:** Demonstrating how to gracefully manage conditions like EndOfFile.\r\n\r\nThese examples are designed to be easily runnable and serve as a quick start for integrating `acfortformat` into your projects.\r\n\r\n---\r\n\r\n## Contributions\r\n\r\nContributions are welcome! If you find a bug or have an improvement, please open an issue or submit a pull request in the GitHub repository.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/acdeveloper-sci/acfortformat/blob/main/LICENSE) file for more details.\r\n\r\n## Contact\r\n\r\nIf you have any questions or suggestions, please feel free to contact me at [ajcs.developer@gmail.com](mailto:ajcs.developer@gmail.com).\r\n\r\n## Autor\r\n\r\n**Adolph Cardozo** \r\n\ud83d\udce7 [ajcs.developer@gmail.com](mailto:ajcs.developer@gmail.com)\r\n\ud83d\udd17 [GitHub](https://github.com/acdeveloper-sci)\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Python library for reading and writing data in Fortran-style and native Python formats.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/acdeveloper-sci/acfortformat",
"Issues": "https://github.com/acdeveloper-sci/acfortformat/issues",
"Source Code": "https://github.com/acdeveloper-sci/acfortformat"
},
"split_keywords": [
"fortran",
" io",
" format",
" read",
" write",
" scientific",
" data processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f5a0337b85d712e384877977025b63cd6bf751bc936c03488f6ca16447c20207",
"md5": "27411c30d52efdad024eb8669ba7f7ce",
"sha256": "0c38dea51a40098cab9f54591c1d7b49811db53440a1ea8ce77f1b7c71e18b2b"
},
"downloads": -1,
"filename": "acfortformat-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27411c30d52efdad024eb8669ba7f7ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10376,
"upload_time": "2025-07-18T22:53:44",
"upload_time_iso_8601": "2025-07-18T22:53:44.544246Z",
"url": "https://files.pythonhosted.org/packages/f5/a0/337b85d712e384877977025b63cd6bf751bc936c03488f6ca16447c20207/acfortformat-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "53e7e3f9b334a70a81d05394a0876f06be9da5129a171aadf9feb2a2647f8fe3",
"md5": "fe87d15f796ea46df759791cb5922866",
"sha256": "e4a2ad83b6ef7147e6d625ae7468ace5058ba36a5e8541d2c8da7d68630468e5"
},
"downloads": -1,
"filename": "acfortformat-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "fe87d15f796ea46df759791cb5922866",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11902,
"upload_time": "2025-07-18T22:53:45",
"upload_time_iso_8601": "2025-07-18T22:53:45.923687Z",
"url": "https://files.pythonhosted.org/packages/53/e7/e3f9b334a70a81d05394a0876f06be9da5129a171aadf9feb2a2647f8fe3/acfortformat-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 22:53:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "acdeveloper-sci",
"github_project": "acfortformat",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "acfortformat"
}
JSON
