detrack 0.1.0__tar.gz

detrack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emiliano Gandini Outeda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detrack-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: detrack
+Version: 0.1.0
+Summary: Strip tracking parameters from URLs. Deterministically. Zero dependencies.
+Author-email: Emiliano Gandini Outeda <emiliano.gandini@protonmail.com>
+License: MIT
+Project-URL: Source, https://github.com/emiliano-gandini-outeda/detrack
+Keywords: seo,tracking,privacy,utm,url-cleaner
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# detrack
+ Strip tracking parameters from URLs. Deterministically. Zero dependencies.

detrack-0.1.0/README.md

@@ -0,0 +1,2 @@
+# detrack
+ Strip tracking parameters from URLs. Deterministically. Zero dependencies.

detrack-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "detrack"
+version = "0.1.0"
+description = "Strip tracking parameters from URLs. Deterministically. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Emiliano Gandini Outeda", email = "emiliano.gandini@protonmail.com" }
+]
+license = { text = "MIT" }
+keywords = ["seo", "tracking", "privacy", "utm", "url-cleaner"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Source = "https://github.com/emiliano-gandini-outeda/detrack"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

detrack-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

detrack-0.1.0/src/detrack/__init__.py

@@ -0,0 +1,4 @@
+from detrack.core import clean, clean_query, DetrackResult
+from detrack.patterns import DEFAULT_PATTERNS
+
+__all__ = ["clean", "clean_query", "DEFAULT_PATTERNS", "DetrackResult"]

detrack-0.1.0/src/detrack/core.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+from urllib.parse import SplitResult
+
+from detrack.patterns import DEFAULT_PATTERNS
+
+
+@dataclass
+class DetrackResult:
+    url: str
+    parsed_url: SplitResult
+    cleaned_params: dict[str, str]
+    removed_params: list[str]
+
+
+def _filter_pairs(
+    query: str,
+    patterns: list[str] | None = None,
+) -> tuple[list[tuple[str, str]], list[str]]:
+    patterns_set = frozenset(p.lower() for p in (patterns or list(DEFAULT_PATTERNS)))
+    pairs = parse_qsl(query, keep_blank_values=True)
+    cleaned: list[tuple[str, str]] = []
+    removed: list[str] = []
+    for key, val in pairs:
+        if key.lower() in patterns_set:
+            removed.append(key)
+        else:
+            cleaned.append((key, val))
+    return cleaned, removed
+
+
+def clean_query(query: str, patterns: list[str] | None = None) -> str:
+    cleaned, _ = _filter_pairs(query, patterns)
+    return urlencode(cleaned, doseq=True)
+
+
+def clean(url: str, patterns: list[str] | None = None) -> DetrackResult:
+    try:
+        parsed = urlsplit(url)
+        if not parsed.query:
+            return DetrackResult(
+                url=url,
+                parsed_url=parsed,
+                cleaned_params={},
+                removed_params=[],
+            )
+        cleaned_pairs, removed = _filter_pairs(parsed.query, patterns)
+        cleaned_qs = urlencode(cleaned_pairs, doseq=True)
+        cleaned_dict = dict(cleaned_pairs)
+        new_url = urlunsplit((
+            parsed.scheme,
+            parsed.netloc,
+            parsed.path,
+            cleaned_qs,
+            parsed.fragment,
+        ))
+        return DetrackResult(
+            url=new_url,
+            parsed_url=parsed,
+            cleaned_params=cleaned_dict,
+            removed_params=removed,
+        )
+    except Exception:
+        return DetrackResult(
+            url=url,
+            parsed_url=urlsplit(""),
+            cleaned_params={},
+            removed_params=[],
+        )

detrack-0.1.0/src/detrack/patterns.py

@@ -0,0 +1,24 @@
+DEFAULT_PATTERNS = frozenset({
+    # UTM
+    "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content",
+    "utm_id", "utm_cid", "utm_reader", "utm_viz", "utm_pubreferrer",
+    "utm_nooverride",
+    # Social
+    "fbclid", "ref", "source", "si", "sns", "social", "origin",
+    # Marketing / Ad
+    "gclid", "gclsrc", "dclid", "msclkid", "wbraid", "gbraid",
+    "mc_cid", "mc_eid", "trk", "vero_conv", "vero_id",
+    "email", "recipient", "campaign_id", "newsletter", "mbid",
+    # Analytics
+    "_ga", "_gl", "_ke", "_hsenc",
+    # Cache busters
+    "_", "cb", "cache", "nocache", "rand", "random", "r", "ts", "_t",
+    "timestamp",
+    # Session / visit
+    "session_id", "sid", "phpsessid", "jsessionid", "view_id", "visit_id",
+    # Redirect
+    "redirect_to", "return_to", "next", "continue",
+    # Misc / platform-specific
+    "yclid", "igshid", "_openstat", "oft_id", "wt_mc", "mtm_source",
+    "mtm_medium", "mtm_campaign", "mtm_keyword", "mtm_content",
+})

detrack-0.1.0/src/detrack.egg-info/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: detrack
+Version: 0.1.0
+Summary: Strip tracking parameters from URLs. Deterministically. Zero dependencies.
+Author-email: Emiliano Gandini Outeda <emiliano.gandini@protonmail.com>
+License: MIT
+Project-URL: Source, https://github.com/emiliano-gandini-outeda/detrack
+Keywords: seo,tracking,privacy,utm,url-cleaner
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# detrack
+ Strip tracking parameters from URLs. Deterministically. Zero dependencies.

detrack-0.1.0/src/detrack.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/detrack/__init__.py
+src/detrack/core.py
+src/detrack/patterns.py
+src/detrack.egg-info/PKG-INFO
+src/detrack.egg-info/SOURCES.txt
+src/detrack.egg-info/dependency_links.txt
+src/detrack.egg-info/requires.txt
+src/detrack.egg-info/top_level.txt
+tests/test_core.py
+tests/test_edge_cases.py
+tests/test_patterns.py

detrack-0.1.0/src/detrack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

detrack-0.1.0/src/detrack.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest

detrack-0.1.0/src/detrack.egg-info/top_level.txt

@@ -0,0 +1 @@
+detrack

detrack-0.1.0/tests/test_core.py

@@ -0,0 +1,86 @@
+from detrack import DetrackResult, clean, clean_query
+
+
+def test_clean_basic() -> None:
+    result = clean("https://example.com/post?utm_source=twitter&q=python")
+    assert result.url == "https://example.com/post?q=python"
+    assert result.cleaned_params == {"q": "python"}
+    assert result.removed_params == ["utm_source"]
+
+
+def test_clean_multiple_trackers() -> None:
+    result = clean("https://example.com?a=1&utm_source=x&b=2&fbclid=y&c=3")
+    assert result.url == "https://example.com?a=1&b=2&c=3"
+    assert result.cleaned_params == {"a": "1", "b": "2", "c": "3"}
+    assert sorted(result.removed_params) == sorted(["utm_source", "fbclid"])
+
+
+def test_clean_all_stripped() -> None:
+    result = clean("https://example.com?utm_source=x&fbclid=y")
+    assert result.url == "https://example.com"
+    assert result.cleaned_params == {}
+    assert sorted(result.removed_params) == sorted(["utm_source", "fbclid"])
+
+
+def test_clean_custom_patterns() -> None:
+    result = clean("https://example.com?session=abc123&page=1", patterns=["session"])
+    assert result.url == "https://example.com?page=1"
+    assert result.cleaned_params == {"page": "1"}
+    assert result.removed_params == ["session"]
+
+
+def test_clean_preserves_fragment() -> None:
+    result = clean("https://example.com/page?utm_source=x#section")
+    assert result.url == "https://example.com/page#section"
+    assert result.removed_params == ["utm_source"]
+
+
+def test_clean_no_query() -> None:
+    result = clean("https://example.com/page")
+    assert result.url == "https://example.com/page"
+    assert result.cleaned_params == {}
+    assert result.removed_params == []
+
+
+def test_clean_empty_url() -> None:
+    result = clean("")
+    assert result.url == ""
+    assert result.cleaned_params == {}
+    assert result.removed_params == []
+
+
+def test_clean_malformed_url() -> None:
+    result = clean("http:///example.com")
+    assert result.removed_params == []
+
+
+def test_clean_query_basic() -> None:
+    result = clean_query("a=1&utm_source=x&b=2")
+    assert result == "a=1&b=2"
+
+
+def test_clean_query_all_stripped() -> None:
+    result = clean_query("utm_source=x&fbclid=y")
+    assert result == ""
+
+
+def test_clean_query_empty() -> None:
+    assert clean_query("") == ""
+
+
+def test_clean_query_no_trackers() -> None:
+    assert clean_query("a=1&b=2") == "a=1&b=2"
+
+
+def test_clean_query_custom_patterns() -> None:
+    result = clean_query("session=abc&page=1", patterns=["session"])
+    assert result == "page=1"
+
+
+def test_detrack_result_fields() -> None:
+    result = clean("https://example.com/p?utm_source=x")
+    assert isinstance(result, DetrackResult)
+    assert hasattr(result, "url")
+    assert hasattr(result, "parsed_url")
+    assert hasattr(result, "cleaned_params")
+    assert hasattr(result, "removed_params")

detrack-0.1.0/tests/test_edge_cases.py

@@ -0,0 +1,85 @@
+from detrack import clean, clean_query
+
+
+def test_case_insensitivity_utm() -> None:
+    for url in [
+        "https://example.com?utm_source=x&q=1",
+        "https://example.com?UTM_SOURCE=x&q=1",
+        "https://example.com?Utm_Source=x&q=1",
+        "https://example.com?utm_SOURCE=x&q=1",
+    ]:
+        result = clean(url)
+        assert result.url == "https://example.com?q=1", f"Failed for {url}"
+        assert result.removed_params == ["utm_source"] or len(result.removed_params) == 1
+
+
+def test_case_insensitivity_fbclid() -> None:
+    for url in [
+        "https://example.com?fbclid=x&q=1",
+        "https://example.com?FBCLID=x&q=1",
+        "https://example.com?Fbclid=x&q=1",
+    ]:
+        result = clean(url)
+        assert result.url == "https://example.com?q=1", f"Failed for {url}"
+
+
+def test_empty_values_preserved_for_non_tracking() -> None:
+    result = clean("https://example.com?a=&b=2")
+    assert result.url == "https://example.com?a=&b=2"
+    assert result.removed_params == []
+
+
+def test_empty_values_removed_for_tracking() -> None:
+    result = clean("https://example.com?utm_source=&b=2")
+    assert result.url == "https://example.com?b=2"
+    assert result.removed_params == ["utm_source"]
+
+
+def test_duplicate_params_all_removed() -> None:
+    result = clean("https://example.com?utm_source=x&utm_source=y&a=1")
+    assert result.url == "https://example.com?a=1"
+    assert result.removed_params == ["utm_source", "utm_source"]
+
+
+def test_url_without_scheme() -> None:
+    result = clean("//example.com/page?utm_source=x")
+    assert "utm_source" not in result.url
+
+
+def test_url_with_port() -> None:
+    result = clean("https://example.com:8080/page?utm_source=x&q=1")
+    assert result.url == "https://example.com:8080/page?q=1"
+
+
+def test_url_with_auth() -> None:
+    result = clean("https://user:pass@example.com/page?utm_source=x&q=1")
+    assert result.url == "https://user:pass@example.com/page?q=1"
+
+
+def test_only_tracking_params_different_cases() -> None:
+    result = clean("https://example.com?UTM_CAMPAIGN=spring&utm_medium=email&q=1")
+    assert result.url == "https://example.com?q=1"
+
+
+def test_no_changes_with_no_tracking() -> None:
+    url = "https://example.com/search?q=python&page=2"
+    result = clean(url)
+    assert result.url == url
+    assert result.cleaned_params == {"q": "python", "page": "2"}
+    assert result.removed_params == []
+
+
+def test_query_only_function_with_mixed() -> None:
+    assert clean_query("a=1&utm_source=x&b=2") == "a=1&b=2"
+
+
+def test_query_only_all_tracking() -> None:
+    assert clean_query("utm_source=x&fbclid=y") == ""
+
+
+def test_query_only_empty() -> None:
+    assert clean_query("") == ""
+
+
+def test_query_only_no_tracking() -> None:
+    assert clean_query("a=1&b=2") == "a=1&b=2"

detrack-0.1.0/tests/test_patterns.py

@@ -0,0 +1,61 @@
+from detrack import DEFAULT_PATTERNS
+
+
+def test_default_patterns_count() -> None:
+    assert len(DEFAULT_PATTERNS) >= 60, (
+        f"DEFAULT_PATTERNS has {len(DEFAULT_PATTERNS)} items, expected >= 60"
+    )
+
+
+def test_utm_params_present() -> None:
+    utm = {"utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content",
+           "utm_id", "utm_cid", "utm_reader", "utm_viz", "utm_pubreferrer",
+           "utm_nooverride"}
+    assert utm.issubset(DEFAULT_PATTERNS), (
+        f"Missing UTM params: {utm - DEFAULT_PATTERNS}"
+    )
+
+
+def test_social_params_present() -> None:
+    social = {"fbclid", "ref", "source", "si", "sns", "social", "origin"}
+    assert social.issubset(DEFAULT_PATTERNS), (
+        f"Missing social params: {social - DEFAULT_PATTERNS}"
+    )
+
+
+def test_marketing_params_present() -> None:
+    marketing = {"gclid", "gclsrc", "dclid", "msclkid", "wbraid", "gbraid",
+                 "mc_cid", "mc_eid", "trk", "vero_conv", "vero_id",
+                 "email", "recipient", "campaign_id", "newsletter", "mbid"}
+    assert marketing.issubset(DEFAULT_PATTERNS), (
+        f"Missing marketing params: {marketing - DEFAULT_PATTERNS}"
+    )
+
+
+def test_analytics_params_present() -> None:
+    analytics = {"_ga", "_gl", "_ke", "_hsenc"}
+    assert analytics.issubset(DEFAULT_PATTERNS), (
+        f"Missing analytics params: {analytics - DEFAULT_PATTERNS}"
+    )
+
+
+def test_cache_busters_present() -> None:
+    cache = {"_", "cb", "cache", "nocache", "rand", "random", "r", "ts", "_t",
+             "timestamp"}
+    assert cache.issubset(DEFAULT_PATTERNS), (
+        f"Missing cache buster params: {cache - DEFAULT_PATTERNS}"
+    )
+
+
+def test_session_params_present() -> None:
+    session = {"session_id", "sid", "phpsessid", "jsessionid", "view_id", "visit_id"}
+    assert session.issubset(DEFAULT_PATTERNS), (
+        f"Missing session params: {session - DEFAULT_PATTERNS}"
+    )
+
+
+def test_redirect_params_present() -> None:
+    redirect = {"redirect_to", "return_to", "next", "continue"}
+    assert redirect.issubset(DEFAULT_PATTERNS), (
+        f"Missing redirect params: {redirect - DEFAULT_PATTERNS}"
+    )