tiny-analytics 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.
Files changed (15) hide show
  1. tiny_analytics-0.1.0/.gitignore +44 -0
  2. tiny_analytics-0.1.0/LICENSE +21 -0
  3. tiny_analytics-0.1.0/PKG-INFO +201 -0
  4. tiny_analytics-0.1.0/README.md +165 -0
  5. tiny_analytics-0.1.0/pyproject.toml +65 -0
  6. tiny_analytics-0.1.0/src/tiny_analytics/__init__.py +3 -0
  7. tiny_analytics-0.1.0/src/tiny_analytics/__main__.py +6 -0
  8. tiny_analytics-0.1.0/src/tiny_analytics/app.py +497 -0
  9. tiny_analytics-0.1.0/src/tiny_analytics/cli.py +34 -0
  10. tiny_analytics-0.1.0/src/tiny_analytics/static/css/style.css +378 -0
  11. tiny_analytics-0.1.0/src/tiny_analytics/static/js/dashboard.js +133 -0
  12. tiny_analytics-0.1.0/src/tiny_analytics/templates/base.html +14 -0
  13. tiny_analytics-0.1.0/src/tiny_analytics/templates/dashboard.html +88 -0
  14. tiny_analytics-0.1.0/src/tiny_analytics/templates/login.html +13 -0
  15. tiny_analytics-0.1.0/src/tiny_analytics/templates/logs.html +69 -0
tiny_analytics-0.1.0/.gitignore ADDED
@@ -0,0 +1,44 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ .Python
7
+ build/
8
+ develop-eggs/
9
+ dist/
10
+ downloads/
11
+ eggs/
12
+ .eggs/
13
+ lib/
14
+ lib64/
15
+ parts/
16
+ sdist/
17
+ var/
18
+ wheels/
19
+ *.egg-info/
20
+ .installed.cfg
21
+ *.egg
22
+
23
+ # Virtual environments
24
+ .venv/
25
+ venv/
26
+ ENV/
27
+
28
+ # IDE
29
+ .idea/
30
+ .vscode/
31
+ *.swp
32
+ *.swo
33
+
34
+ # Testing
35
+ .pytest_cache/
36
+ .coverage
37
+ htmlcov/
38
+
39
+ # Local config
40
+ .env
41
+ *.db
42
+
43
+ # uv
44
+ uv.lock
tiny_analytics-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zev Averbach
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.
tiny_analytics-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,201 @@
1
+ Metadata-Version: 2.4
2
+ Name: tiny-analytics
3
+ Version: 0.1.0
4
+ Summary: Minimal, privacy-focused web analytics
5
+ Project-URL: Homepage, https://github.com/zevaverbach/tiny-analytics
6
+ Project-URL: Repository, https://github.com/zevaverbach/tiny-analytics
7
+ Project-URL: Issues, https://github.com/zevaverbach/tiny-analytics/issues
8
+ Author-email: Zev Averbach <zev@averba.ch>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: analytics,privacy,self-hosted,web
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Web Environment
14
+ Classifier: Framework :: FastAPI
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
24
+ Requires-Python: >=3.10
25
+ Requires-Dist: fastapi>=0.115.0
26
+ Requires-Dist: itsdangerous>=2.2.0
27
+ Requires-Dist: jinja2>=3.1.0
28
+ Requires-Dist: pydantic-settings>=2.0
29
+ Requires-Dist: pydantic>=2.0
30
+ Requires-Dist: python-multipart>=0.0.12
31
+ Requires-Dist: uvicorn>=0.32.0
32
+ Provides-Extra: dev
33
+ Requires-Dist: httpx>=0.27.0; extra == 'dev'
34
+ Requires-Dist: pytest>=8.0; extra == 'dev'
35
+ Description-Content-Type: text/markdown
36
+
37
+ # tiny-analytics
38
+
39
+ Minimal, privacy-focused web analytics. Self-hosted, no cookies, no tracking IDs.
40
+
41
+ ![Dashboard](docs/dashboard.png)
42
+
43
+ ## Quick Start
44
+
45
+ ```bash
46
+ # Install
47
+ uv tool install tiny-analytics
48
+
49
+ # Configure (create a .env file or set environment variables)
50
+ export TINY_ANALYTICS_PASSWORD="your-secret-password"
51
+ export TINY_ANALYTICS_SECRET_KEY="$(openssl rand -hex 32)"
52
+
53
+ # Run
54
+ tiny-analytics
55
+ ```
56
+
57
+ Add this to your site:
58
+ ```html
59
+ <script src="https://your-analytics-domain/snippet.js" defer></script>
60
+ ```
61
+
62
+ That's it. View your dashboard at `http://localhost:8000/`.
63
+
64
+ ### One-liner (no install)
65
+
66
+ ```bash
67
+ uvx tiny-analytics
68
+ ```
69
+
70
+ ### From source
71
+
72
+ ```bash
73
+ git clone https://github.com/zevaverbach/tiny-analytics.git
74
+ cd tiny-analytics
75
+ uv sync
76
+ uv run tiny-analytics
77
+ ```
78
+
79
+ <details>
80
+ <summary>Using pip instead of uv</summary>
81
+
82
+ ```bash
83
+ pip install tiny-analytics
84
+ tiny-analytics
85
+ ```
86
+
87
+ Or from source:
88
+ ```bash
89
+ git clone https://github.com/zevaverbach/tiny-analytics.git
90
+ cd tiny-analytics
91
+ python -m venv .venv && source .venv/bin/activate
92
+ pip install -e .
93
+ tiny-analytics
94
+ ```
95
+ </details>
96
+
97
+ ---
98
+
99
+ ## Features
100
+
101
+ - **Privacy-first**: No cookies, no fingerprinting, no personal data stored
102
+ - **Lightweight**: Single Python file + templates
103
+ - **Bot filtering**: Automatic detection and separation of bot traffic
104
+ - **Time on page**: Tracks actual engagement, not just page loads
105
+ - **Geo & device breakdown**: See where your visitors come from and what they use
106
+ - **Dark mode UI**: Easy on the eyes
107
+
108
+ ## Screenshots
109
+
110
+ <details>
111
+ <summary>Login</summary>
112
+
113
+ ![Login](docs/login.png)
114
+ </details>
115
+
116
+ <details>
117
+ <summary>Logs view</summary>
118
+
119
+ ![Logs](docs/logs.jpg)
120
+ </details>
121
+
122
+ ## How It Works
123
+
124
+ 1. **Visitor hits your page** → snippet.js fires a POST to `/t`
125
+ 2. **Server hashes IP+UA** → creates anonymous visitor ID (never stored raw)
126
+ 3. **On page leave** → beacon sends time-on-page to `/d`
127
+ 4. **Dashboard** → aggregates and visualizes the data
128
+
129
+ No cookies. No localStorage. No tracking across sites.
130
+
131
+ ## Configuration
132
+
133
+ | Variable | Default | Description |
134
+ |----------|---------|-------------|
135
+ | `TINY_ANALYTICS_PASSWORD` | `changeme` | Dashboard login password |
136
+ | `TINY_ANALYTICS_SECRET_KEY` | `change-this...` | Session signing key (generate a random string) |
137
+ | `TINY_ANALYTICS_ALLOWED_ORIGINS` | `[]` | Restrict tracking to specific domains (empty = allow all) |
138
+ | `TINY_ANALYTICS_DB_PATH` | `./tiny_analytics.db` | SQLite database location |
139
+ | `TINY_ANALYTICS_HOST` | `0.0.0.0` | Host to bind to |
140
+ | `TINY_ANALYTICS_PORT` | `8000` | Port to listen on |
141
+
142
+ ## Deployment
143
+
144
+ ### Systemd
145
+
146
+ ```ini
147
+ [Unit]
148
+ Description=tiny-analytics
149
+ After=network.target
150
+
151
+ [Service]
152
+ User=www-data
153
+ WorkingDirectory=/opt/tiny-analytics
154
+ Environment="TINY_ANALYTICS_PASSWORD=your-password"
155
+ Environment="TINY_ANALYTICS_SECRET_KEY=your-secret-key"
156
+ ExecStart=/usr/local/bin/tiny-analytics
157
+ Restart=always
158
+
159
+ [Install]
160
+ WantedBy=multi-user.target
161
+ ```
162
+
163
+ ### Behind nginx
164
+
165
+ ```nginx
166
+ location / {
167
+ proxy_pass http://127.0.0.1:8000;
168
+ proxy_set_header Host $host;
169
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
170
+ proxy_set_header X-Forwarded-Proto $scheme;
171
+ }
172
+ ```
173
+
174
+ ### Cloudflare
175
+
176
+ tiny-analytics reads `cf-connecting-ip` and `cf-ipcountry` headers automatically for accurate geo and IP data behind Cloudflare.
177
+
178
+ ## CLI Options
179
+
180
+ ```
181
+ tiny-analytics [OPTIONS]
182
+
183
+ Options:
184
+ --host TEXT Host to bind to [default: 0.0.0.0]
185
+ --port INTEGER Port to listen on [default: 8000]
186
+ --help Show this message and exit
187
+ ```
188
+
189
+ ## API
190
+
191
+ | Endpoint | Method | Description |
192
+ |----------|--------|-------------|
193
+ | `/t` | POST | Record a pageview |
194
+ | `/d` | POST | Update time-on-page |
195
+ | `/snippet.js` | GET | Tracking script |
196
+ | `/` | GET | Dashboard (auth required) |
197
+ | `/logs` | GET | Raw logs view (auth required) |
198
+
199
+ ## License
200
+
201
+ MIT
tiny_analytics-0.1.0/README.md ADDED
@@ -0,0 +1,165 @@
1
+ # tiny-analytics
2
+
3
+ Minimal, privacy-focused web analytics. Self-hosted, no cookies, no tracking IDs.
4
+
5
+ ![Dashboard](docs/dashboard.png)
6
+
7
+ ## Quick Start
8
+
9
+ ```bash
10
+ # Install
11
+ uv tool install tiny-analytics
12
+
13
+ # Configure (create a .env file or set environment variables)
14
+ export TINY_ANALYTICS_PASSWORD="your-secret-password"
15
+ export TINY_ANALYTICS_SECRET_KEY="$(openssl rand -hex 32)"
16
+
17
+ # Run
18
+ tiny-analytics
19
+ ```
20
+
21
+ Add this to your site:
22
+ ```html
23
+ <script src="https://your-analytics-domain/snippet.js" defer></script>
24
+ ```
25
+
26
+ That's it. View your dashboard at `http://localhost:8000/`.
27
+
28
+ ### One-liner (no install)
29
+
30
+ ```bash
31
+ uvx tiny-analytics
32
+ ```
33
+
34
+ ### From source
35
+
36
+ ```bash
37
+ git clone https://github.com/zevaverbach/tiny-analytics.git
38
+ cd tiny-analytics
39
+ uv sync
40
+ uv run tiny-analytics
41
+ ```
42
+
43
+ <details>
44
+ <summary>Using pip instead of uv</summary>
45
+
46
+ ```bash
47
+ pip install tiny-analytics
48
+ tiny-analytics
49
+ ```
50
+
51
+ Or from source:
52
+ ```bash
53
+ git clone https://github.com/zevaverbach/tiny-analytics.git
54
+ cd tiny-analytics
55
+ python -m venv .venv && source .venv/bin/activate
56
+ pip install -e .
57
+ tiny-analytics
58
+ ```
59
+ </details>
60
+
61
+ ---
62
+
63
+ ## Features
64
+
65
+ - **Privacy-first**: No cookies, no fingerprinting, no personal data stored
66
+ - **Lightweight**: Single Python file + templates
67
+ - **Bot filtering**: Automatic detection and separation of bot traffic
68
+ - **Time on page**: Tracks actual engagement, not just page loads
69
+ - **Geo & device breakdown**: See where your visitors come from and what they use
70
+ - **Dark mode UI**: Easy on the eyes
71
+
72
+ ## Screenshots
73
+
74
+ <details>
75
+ <summary>Login</summary>
76
+
77
+ ![Login](docs/login.png)
78
+ </details>
79
+
80
+ <details>
81
+ <summary>Logs view</summary>
82
+
83
+ ![Logs](docs/logs.jpg)
84
+ </details>
85
+
86
+ ## How It Works
87
+
88
+ 1. **Visitor hits your page** → snippet.js fires a POST to `/t`
89
+ 2. **Server hashes IP+UA** → creates anonymous visitor ID (never stored raw)
90
+ 3. **On page leave** → beacon sends time-on-page to `/d`
91
+ 4. **Dashboard** → aggregates and visualizes the data
92
+
93
+ No cookies. No localStorage. No tracking across sites.
94
+
95
+ ## Configuration
96
+
97
+ | Variable | Default | Description |
98
+ |----------|---------|-------------|
99
+ | `TINY_ANALYTICS_PASSWORD` | `changeme` | Dashboard login password |
100
+ | `TINY_ANALYTICS_SECRET_KEY` | `change-this...` | Session signing key (generate a random string) |
101
+ | `TINY_ANALYTICS_ALLOWED_ORIGINS` | `[]` | Restrict tracking to specific domains (empty = allow all) |
102
+ | `TINY_ANALYTICS_DB_PATH` | `./tiny_analytics.db` | SQLite database location |
103
+ | `TINY_ANALYTICS_HOST` | `0.0.0.0` | Host to bind to |
104
+ | `TINY_ANALYTICS_PORT` | `8000` | Port to listen on |
105
+
106
+ ## Deployment
107
+
108
+ ### Systemd
109
+
110
+ ```ini
111
+ [Unit]
112
+ Description=tiny-analytics
113
+ After=network.target
114
+
115
+ [Service]
116
+ User=www-data
117
+ WorkingDirectory=/opt/tiny-analytics
118
+ Environment="TINY_ANALYTICS_PASSWORD=your-password"
119
+ Environment="TINY_ANALYTICS_SECRET_KEY=your-secret-key"
120
+ ExecStart=/usr/local/bin/tiny-analytics
121
+ Restart=always
122
+
123
+ [Install]
124
+ WantedBy=multi-user.target
125
+ ```
126
+
127
+ ### Behind nginx
128
+
129
+ ```nginx
130
+ location / {
131
+ proxy_pass http://127.0.0.1:8000;
132
+ proxy_set_header Host $host;
133
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
134
+ proxy_set_header X-Forwarded-Proto $scheme;
135
+ }
136
+ ```
137
+
138
+ ### Cloudflare
139
+
140
+ tiny-analytics reads `cf-connecting-ip` and `cf-ipcountry` headers automatically for accurate geo and IP data behind Cloudflare.
141
+
142
+ ## CLI Options
143
+
144
+ ```
145
+ tiny-analytics [OPTIONS]
146
+
147
+ Options:
148
+ --host TEXT Host to bind to [default: 0.0.0.0]
149
+ --port INTEGER Port to listen on [default: 8000]
150
+ --help Show this message and exit
151
+ ```
152
+
153
+ ## API
154
+
155
+ | Endpoint | Method | Description |
156
+ |----------|--------|-------------|
157
+ | `/t` | POST | Record a pageview |
158
+ | `/d` | POST | Update time-on-page |
159
+ | `/snippet.js` | GET | Tracking script |
160
+ | `/` | GET | Dashboard (auth required) |
161
+ | `/logs` | GET | Raw logs view (auth required) |
162
+
163
+ ## License
164
+
165
+ MIT
tiny_analytics-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,65 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "tiny-analytics"
7
+ version = "0.1.0"
8
+ description = "Minimal, privacy-focused web analytics"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ authors = [
12
+ { name = "Zev Averbach", email = "zev@averba.ch" }
13
+ ]
14
+ keywords = ["analytics", "privacy", "web", "self-hosted"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Environment :: Web Environment",
18
+ "Framework :: FastAPI",
19
+ "Intended Audience :: Developers",
20
+ "License :: OSI Approved :: MIT License",
21
+ "Operating System :: OS Independent",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
28
+ ]
29
+ requires-python = ">=3.10"
30
+ dependencies = [
31
+ "fastapi>=0.115.0",
32
+ "uvicorn>=0.32.0",
33
+ "pydantic>=2.0",
34
+ "pydantic-settings>=2.0",
35
+ "python-multipart>=0.0.12",
36
+ "itsdangerous>=2.2.0",
37
+ "jinja2>=3.1.0",
38
+ ]
39
+
40
+ [project.optional-dependencies]
41
+ dev = [
42
+ "pytest>=8.0",
43
+ "httpx>=0.27.0",
44
+ ]
45
+
46
+ [project.scripts]
47
+ tiny-analytics = "tiny_analytics.cli:main"
48
+
49
+ [project.urls]
50
+ Homepage = "https://github.com/zevaverbach/tiny-analytics"
51
+ Repository = "https://github.com/zevaverbach/tiny-analytics"
52
+ Issues = "https://github.com/zevaverbach/tiny-analytics/issues"
53
+
54
+ [tool.hatch.build.targets.sdist]
55
+ include = [
56
+ "/src",
57
+ "/README.md",
58
+ "/LICENSE",
59
+ ]
60
+
61
+ [tool.hatch.build.targets.wheel]
62
+ packages = ["src/tiny_analytics"]
63
+
64
+ [tool.pytest.ini_options]
65
+ testpaths = ["tests"]
tiny_analytics-0.1.0/src/tiny_analytics/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """tiny-analytics - Minimal, privacy-focused web analytics."""
2
+
3
+ __version__ = "0.1.0"
tiny_analytics-0.1.0/src/tiny_analytics/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """CLI entry point for tiny-analytics."""
2
+
3
+ from tiny_analytics.cli import main
4
+
5
+ if __name__ == "__main__":
6
+ main()