thf 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
thf-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 TaeinYoon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
thf-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,135 @@
1
+ Metadata-Version: 2.4
2
+ Name: thf
3
+ Version: 0.1.0
4
+ Summary: A terminal UI for managing Hugging Face models, datasets and caches on shared servers
5
+ Author: TaeinYoon
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Taepoung/thf
8
+ Project-URL: Repository, https://github.com/Taepoung/thf
9
+ Project-URL: Issues, https://github.com/Taepoung/thf/issues
10
+ Keywords: huggingface,tui,cache,models,textual
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Python :: 3
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: textual<9,>=8.2
21
+ Requires-Dist: huggingface_hub<3,>=2.4
22
+ Dynamic: license-file
23
+
24
+ # thf — Hugging Face manager TUI
25
+
26
+ A terminal UI for managing Hugging Face models and datasets on shared GPU servers.
27
+ See what is in the cache and when it was last used, download only the files you need,
28
+ clean up old revisions, and manage your own repositories on the Hub.
29
+
30
+ ## Features
31
+
32
+ - **Models / Datasets / Spaces**: what is in the cache, one tab per type, with size, revisions and last use
33
+ - filter by name: every word you type must appear (e.g. `qwen 7b`)
34
+ - filter and sort like the Hub (`f`): task, parameters, library, language, license, gated, dataset size;
35
+ sort by size, last use or name. Details come from the Hub once per repo and are kept for a week
36
+ - details: revisions and the branches pointing to them, the local snapshot path to use in code
37
+ - pull the latest version, remove old revisions, delete
38
+ - **Hub**: search models, datasets and spaces with the same filters as the website
39
+ (task, parameters, library, runs with, language, license, gated or not, dataset size, sort order);
40
+ see size, license, task and the largest files before downloading
41
+ - **Download** from a form
42
+ - include / exclude patterns (e.g. only `*.safetensors *.json`) with a live file count and total size
43
+ - any branch, tag or commit
44
+ - into the HF cache or into a plain local folder
45
+ - progress with speed; runs in the background so you can keep working
46
+ - **My repos** (after logging in): your and your organizations' repositories; create, make public/private, delete
47
+ - **Cleanup**: disk usage, and removal of old revisions, incomplete downloads and orphaned shared files
48
+
49
+ ## Requirements
50
+
51
+ - Linux
52
+ - Python 3.10+
53
+
54
+ ## Install
55
+
56
+ Pick one. All of them give you a `thf` command.
57
+
58
+ | Method | Command | Good for |
59
+ |---|---|---|
60
+ | **uv** (recommended) | `uv tool install thf` | Any Linux. No Python setup needed: uv downloads a Python if yours is missing or too old |
61
+ | **pipx** | `pipx install thf` | If you already use pipx |
62
+ | **pip** | `pip install thf` | Inside a conda env or virtualenv you already use |
63
+ | **Install script** | see below | Uses your Python 3.10+ if usable, otherwise falls back to uv |
64
+
65
+ ### Install script
66
+
67
+ ```bash
68
+ curl -fsSL https://raw.githubusercontent.com/Taepoung/thf/main/install.sh | bash
69
+ # uninstall
70
+ curl -fsSL https://raw.githubusercontent.com/Taepoung/thf/main/install.sh | bash -s -- --uninstall
71
+ ```
72
+
73
+ Installs into `~/.local/share/thf` and links `~/.local/bin/thf`.
74
+
75
+ ### Update / uninstall
76
+
77
+ | Method | Update | Uninstall |
78
+ |---|---|---|
79
+ | uv | `uv tool upgrade thf` | `uv tool uninstall thf` |
80
+ | pipx | `pipx upgrade thf` | `pipx uninstall thf` |
81
+ | pip | `pip install -U thf` | `pip uninstall thf` |
82
+
83
+ ## Usage
84
+
85
+ ```bash
86
+ thf # start
87
+ thf --cache-dir /path/hub # manage another cache for this run (overrides Settings)
88
+ thf --version
89
+ ```
90
+
91
+ | Tab | Keys |
92
+ |---|---|
93
+ | Models / Datasets / Spaces | `/` filter by name, `f` filters, `p` pull latest, `x` remove old revisions, `d` delete |
94
+ | Hub | `/` search box, `f` filters, `Enter` search, `p` or `Enter` download |
95
+ | Hub filters | `Ctrl+R` apply, `Esc` cancel |
96
+ | My repos | `/` filter, `n` new, `p` download, `v` public/private, `d` delete |
97
+ | Download form | `Ctrl+R` download, `Esc` cancel |
98
+ | Everywhere | `←` `→` previous / next tab, `s` settings (log in here), `r` refresh this tab, `Esc` leave a text box, `q` quit |
99
+
100
+ ## Notes
101
+
102
+ - **Deleting** always asks "Really delete …?" first (`y` to confirm). Deleting a repository on the Hub
103
+ asks you to type its name, because that cannot be undone.
104
+ - **Shared caches**: when several people point `HF_HUB_CACHE` at the same folder, deleting from the cache
105
+ removes it for everyone. thf cannot tell who is using a model: Linux records only when a file was last read.
106
+ Files shared between repos (huggingface_hub's shared blob store) are kept until nothing refers to them.
107
+ - **Login** is handled entirely by the `hf` CLI, so the token is shared with `hf`, `transformers` and other tools.
108
+ If the token comes from the `HF_TOKEN` environment variable, unset it to log out.
109
+ - **Gated models** (e.g. Llama, Gemma): accept the terms on the model page first, then log in with a token that can read them.
110
+ - **Old revisions** are left behind when a repo is updated: the branch moves to a new commit and the old files stay.
111
+ Code pinned to an old commit would download it again.
112
+ - **Last used** is the last time any file of the repo was read (file access time). On most Linux systems
113
+ it is updated at most about once a day, and any read counts (a backup, `grep -r`), not only loading the model.
114
+ - **Incomplete downloads** are partial files from interrupted downloads. Remove them only when no download is running.
115
+
116
+ ## Settings
117
+
118
+ The Settings tab (`s`):
119
+
120
+ - **Hugging Face account**: Log in, Switch token and Log out run `hf auth login` / `hf auth switch` / `hf auth logout`
121
+ in the terminal (browser or token login, exactly as the `hf` CLI does), then return to thf.
122
+ Needed for My repos and for private or gated models.
123
+ - **Cache folder**: the cache thf opens by default. Empty means `HF_HUB_CACHE` (or `~/.cache/huggingface/hub`).
124
+ Press Apply (or Enter) to switch to it.
125
+
126
+ Changes are saved right away.
127
+
128
+ ## Files
129
+
130
+ - `~/.config/thf/config.json`: settings (cache folder)
131
+ - `~/.cache/thf/hub_info.json`: Hub details of downloaded repos (task, library, tags, parameters), used by the filters
132
+
133
+ ## License
134
+
135
+ MIT
thf-0.1.0/README.md ADDED
@@ -0,0 +1,112 @@
1
+ # thf — Hugging Face manager TUI
2
+
3
+ A terminal UI for managing Hugging Face models and datasets on shared GPU servers.
4
+ See what is in the cache and when it was last used, download only the files you need,
5
+ clean up old revisions, and manage your own repositories on the Hub.
6
+
7
+ ## Features
8
+
9
+ - **Models / Datasets / Spaces**: what is in the cache, one tab per type, with size, revisions and last use
10
+ - filter by name: every word you type must appear (e.g. `qwen 7b`)
11
+ - filter and sort like the Hub (`f`): task, parameters, library, language, license, gated, dataset size;
12
+ sort by size, last use or name. Details come from the Hub once per repo and are kept for a week
13
+ - details: revisions and the branches pointing to them, the local snapshot path to use in code
14
+ - pull the latest version, remove old revisions, delete
15
+ - **Hub**: search models, datasets and spaces with the same filters as the website
16
+ (task, parameters, library, runs with, language, license, gated or not, dataset size, sort order);
17
+ see size, license, task and the largest files before downloading
18
+ - **Download** from a form
19
+ - include / exclude patterns (e.g. only `*.safetensors *.json`) with a live file count and total size
20
+ - any branch, tag or commit
21
+ - into the HF cache or into a plain local folder
22
+ - progress with speed; runs in the background so you can keep working
23
+ - **My repos** (after logging in): your and your organizations' repositories; create, make public/private, delete
24
+ - **Cleanup**: disk usage, and removal of old revisions, incomplete downloads and orphaned shared files
25
+
26
+ ## Requirements
27
+
28
+ - Linux
29
+ - Python 3.10+
30
+
31
+ ## Install
32
+
33
+ Pick one. All of them give you a `thf` command.
34
+
35
+ | Method | Command | Good for |
36
+ |---|---|---|
37
+ | **uv** (recommended) | `uv tool install thf` | Any Linux. No Python setup needed: uv downloads a Python if yours is missing or too old |
38
+ | **pipx** | `pipx install thf` | If you already use pipx |
39
+ | **pip** | `pip install thf` | Inside a conda env or virtualenv you already use |
40
+ | **Install script** | see below | Uses your Python 3.10+ if usable, otherwise falls back to uv |
41
+
42
+ ### Install script
43
+
44
+ ```bash
45
+ curl -fsSL https://raw.githubusercontent.com/Taepoung/thf/main/install.sh | bash
46
+ # uninstall
47
+ curl -fsSL https://raw.githubusercontent.com/Taepoung/thf/main/install.sh | bash -s -- --uninstall
48
+ ```
49
+
50
+ Installs into `~/.local/share/thf` and links `~/.local/bin/thf`.
51
+
52
+ ### Update / uninstall
53
+
54
+ | Method | Update | Uninstall |
55
+ |---|---|---|
56
+ | uv | `uv tool upgrade thf` | `uv tool uninstall thf` |
57
+ | pipx | `pipx upgrade thf` | `pipx uninstall thf` |
58
+ | pip | `pip install -U thf` | `pip uninstall thf` |
59
+
60
+ ## Usage
61
+
62
+ ```bash
63
+ thf # start
64
+ thf --cache-dir /path/hub # manage another cache for this run (overrides Settings)
65
+ thf --version
66
+ ```
67
+
68
+ | Tab | Keys |
69
+ |---|---|
70
+ | Models / Datasets / Spaces | `/` filter by name, `f` filters, `p` pull latest, `x` remove old revisions, `d` delete |
71
+ | Hub | `/` search box, `f` filters, `Enter` search, `p` or `Enter` download |
72
+ | Hub filters | `Ctrl+R` apply, `Esc` cancel |
73
+ | My repos | `/` filter, `n` new, `p` download, `v` public/private, `d` delete |
74
+ | Download form | `Ctrl+R` download, `Esc` cancel |
75
+ | Everywhere | `←` `→` previous / next tab, `s` settings (log in here), `r` refresh this tab, `Esc` leave a text box, `q` quit |
76
+
77
+ ## Notes
78
+
79
+ - **Deleting** always asks "Really delete …?" first (`y` to confirm). Deleting a repository on the Hub
80
+ asks you to type its name, because that cannot be undone.
81
+ - **Shared caches**: when several people point `HF_HUB_CACHE` at the same folder, deleting from the cache
82
+ removes it for everyone. thf cannot tell who is using a model: Linux records only when a file was last read.
83
+ Files shared between repos (huggingface_hub's shared blob store) are kept until nothing refers to them.
84
+ - **Login** is handled entirely by the `hf` CLI, so the token is shared with `hf`, `transformers` and other tools.
85
+ If the token comes from the `HF_TOKEN` environment variable, unset it to log out.
86
+ - **Gated models** (e.g. Llama, Gemma): accept the terms on the model page first, then log in with a token that can read them.
87
+ - **Old revisions** are left behind when a repo is updated: the branch moves to a new commit and the old files stay.
88
+ Code pinned to an old commit would download it again.
89
+ - **Last used** is the last time any file of the repo was read (file access time). On most Linux systems
90
+ it is updated at most about once a day, and any read counts (a backup, `grep -r`), not only loading the model.
91
+ - **Incomplete downloads** are partial files from interrupted downloads. Remove them only when no download is running.
92
+
93
+ ## Settings
94
+
95
+ The Settings tab (`s`):
96
+
97
+ - **Hugging Face account**: Log in, Switch token and Log out run `hf auth login` / `hf auth switch` / `hf auth logout`
98
+ in the terminal (browser or token login, exactly as the `hf` CLI does), then return to thf.
99
+ Needed for My repos and for private or gated models.
100
+ - **Cache folder**: the cache thf opens by default. Empty means `HF_HUB_CACHE` (or `~/.cache/huggingface/hub`).
101
+ Press Apply (or Enter) to switch to it.
102
+
103
+ Changes are saved right away.
104
+
105
+ ## Files
106
+
107
+ - `~/.config/thf/config.json`: settings (cache folder)
108
+ - `~/.cache/thf/hub_info.json`: Hub details of downloaded repos (task, library, tags, parameters), used by the filters
109
+
110
+ ## License
111
+
112
+ MIT
@@ -0,0 +1,34 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "thf"
7
+ dynamic = ["version"]
8
+ description = "A terminal UI for managing Hugging Face models, datasets and caches on shared servers"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "TaeinYoon" }]
13
+ keywords = ["huggingface", "tui", "cache", "models", "textual"]
14
+ requires-python = ">=3.10"
15
+ dependencies = ["textual>=8.2,<9", "huggingface_hub>=2.4,<3"]
16
+ classifiers = [
17
+ "Environment :: Console",
18
+ "Intended Audience :: Developers",
19
+ "Intended Audience :: Science/Research",
20
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
21
+ "Operating System :: POSIX :: Linux",
22
+ "Programming Language :: Python :: 3",
23
+ ]
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/Taepoung/thf"
27
+ Repository = "https://github.com/Taepoung/thf"
28
+ Issues = "https://github.com/Taepoung/thf/issues"
29
+
30
+ [project.scripts]
31
+ thf = "thf.app:main"
32
+
33
+ [tool.setuptools.dynamic]
34
+ version = { attr = "thf.__version__" }
thf-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """thf: a terminal UI for managing Hugging Face models and datasets."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from .app import main
2
+
3
+ main()