| Name | tato JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | None |
| Summary | Python file layout formatter. |
| upload_time | 2024-09-04 13:58:01 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
autoformat
format
layout
sections
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# tato
[](https://pypi.org/project/tato)
[](https://pypi.org/project/tato)
-----
Tato is Python file layout formatter. In contrast to other autoformatters,
tato only formats the organization/layout of a file. It tries to organize files
into four sections: imports, constants, classes, and functions.
Here's a (contrived) example to illustrate the idea
<img width="971"
alt="Image showing source code before and after running tato."
src="https://github.com/user-attachments/assets/f3d41f13-af5b-483d-a848-8475d0c63fe5">
## Quick start
```console
pip install tato
tato format <path_to_file>
```
- Tato should be used alongside other autoformatters like black or ruff.
- Tato is probably too disruptive to run on save.
- If the output from tato is confusing, consider splitting the file into smaller
chunks and running tato on each chunk.
- It's fine (even encouraged) to use tato to "reset" a file, but then apply the
finishing touches manually. It'll never be better than a thoughtful layout, but
it's often much better than random layouts.
## Motivation
In large, mature codebases, it’s common to encounter files that lack a coherent
structure. While the initial version of a file may have been thoughtfully
crafted with a logical organization, this structure often erodes over time.
(There are many reasons for this erosion, but that’s a topic for another time.)
Tato offers a reset button, providing consistency by deterministically
organizing the file. While it may not be the optimal layout, this consistency
should reduce the cognitive load required to understand the code.
## Layout details
Tato organizes files into four main sections:
1. Imports
2. Constants
3. Classes
4. Functions
**Imports:** Tato preserves the original import order, leaving the task of
sorting to tools like isort or ruff.
**Constants:** Constants are moved to the top of the file. Typically, these have
brief definitions and act as key control points for program behavior.
**Classes:** Classes are arranged according to their inheritance hierarchy, with
base classes appearing first.
**Functions:** Functions are placed in the final section and sorted by call
hierarchy. This order places the `main()` function first, ensuring that the most
important functions appear at the top.
### Handling Interdependencies
Strict adherence to this four-section layout may not always be possible due to
interdependencies. For example, a constant might depend on a class or function
definition. In such cases, Tato will elevate the necessary definitions to
maintain file validity. These elevated definitions form valid subsections
(constants, classes, functions), although most fields in these subsections are
typically empty.
If a file has too many subsections, it’s likely a sign that it should be broken
up.
Raw data
{
"_id": null,
"home_page": null,
"name": "tato",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "autoformat, format, layout, sections",
"author": null,
"author_email": "Vivek Dasari <vivster7@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/22/4d/65f81fcda63fdf296414dc8a6b854b1c1e17c46b86a08d128b39f95ece31/tato-0.2.3.tar.gz",
"platform": null,
"description": "# tato\n\n[](https://pypi.org/project/tato)\n[](https://pypi.org/project/tato)\n\n-----\n\nTato is Python file layout formatter. In contrast to other autoformatters,\ntato only formats the organization/layout of a file. It tries to organize files\ninto four sections: imports, constants, classes, and functions.\n\nHere's a (contrived) example to illustrate the idea\n<img width=\"971\" \n alt=\"Image showing source code before and after running tato.\" \n src=\"https://github.com/user-attachments/assets/f3d41f13-af5b-483d-a848-8475d0c63fe5\">\n\n\n## Quick start\n\n```console\npip install tato\ntato format <path_to_file>\n```\n- Tato should be used alongside other autoformatters like black or ruff.\n- Tato is probably too disruptive to run on save.\n- If the output from tato is confusing, consider splitting the file into smaller\nchunks and running tato on each chunk.\n- It's fine (even encouraged) to use tato to \"reset\" a file, but then apply the\nfinishing touches manually. It'll never be better than a thoughtful layout, but\nit's often much better than random layouts.\n\n## Motivation\n\nIn large, mature codebases, it\u2019s common to encounter files that lack a coherent\nstructure. While the initial version of a file may have been thoughtfully \ncrafted with a logical organization, this structure often erodes over time. \n(There are many reasons for this erosion, but that\u2019s a topic for another time.)\n\nTato offers a reset button, providing consistency by deterministically \norganizing the file. While it may not be the optimal layout, this consistency\nshould reduce the cognitive load required to understand the code.\n\n## Layout details\n\nTato organizes files into four main sections:\n\n1.\tImports\n2.\tConstants\n3.\tClasses\n4.\tFunctions\n\n**Imports:** Tato preserves the original import order, leaving the task of \nsorting to tools like isort or ruff.\n\n**Constants:** Constants are moved to the top of the file. Typically, these have\nbrief definitions and act as key control points for program behavior.\n\n**Classes:** Classes are arranged according to their inheritance hierarchy, with\nbase classes appearing first.\n\n**Functions:** Functions are placed in the final section and sorted by call \nhierarchy. This order places the `main()` function first, ensuring that the most \nimportant functions appear at the top.\n\n### Handling Interdependencies\nStrict adherence to this four-section layout may not always be possible due to \ninterdependencies. For example, a constant might depend on a class or function \ndefinition. In such cases, Tato will elevate the necessary definitions to \nmaintain file validity. These elevated definitions form valid subsections \n(constants, classes, functions), although most fields in these subsections are\ntypically empty.\n\nIf a file has too many subsections, it\u2019s likely a sign that it should be broken\n up.",
"bugtrack_url": null,
"license": null,
"summary": "Python file layout formatter.",
"version": "0.2.3",
"project_urls": {
"Documentation": "https://github.com/vivster7/tato#readme",
"Issues": "https://github.com/vivster7/tato/issues",
"Source": "https://github.com/vivster7/tato"
},
"split_keywords": [
"autoformat",
" format",
" layout",
" sections"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "147d8f66bd1f50ac14d7f567c7cdf5dbdfbfdcd253710c6200293b0a5bb5d617",
"md5": "1771fe1643ad5787d9fa2e1fface101b",
"sha256": "62f31550462a76c67277e61721a82b491c689ffdac75bc9eb9b70436a697e05c"
},
"downloads": -1,
"filename": "tato-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1771fe1643ad5787d9fa2e1fface101b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27239,
"upload_time": "2024-09-04T13:58:00",
"upload_time_iso_8601": "2024-09-04T13:58:00.884205Z",
"url": "https://files.pythonhosted.org/packages/14/7d/8f66bd1f50ac14d7f567c7cdf5dbdfbfdcd253710c6200293b0a5bb5d617/tato-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "224d65f81fcda63fdf296414dc8a6b854b1c1e17c46b86a08d128b39f95ece31",
"md5": "47e807c1add818da6978e68019527d57",
"sha256": "d4be720539d5a2ce35fcef67312ee011f033268a0bd66a3e9ec407be0ff7a254"
},
"downloads": -1,
"filename": "tato-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "47e807c1add818da6978e68019527d57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18229,
"upload_time": "2024-09-04T13:58:01",
"upload_time_iso_8601": "2024-09-04T13:58:01.928147Z",
"url": "https://files.pythonhosted.org/packages/22/4d/65f81fcda63fdf296414dc8a6b854b1c1e17c46b86a08d128b39f95ece31/tato-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-04 13:58:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vivster7",
"github_project": "tato#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tato"
}
