{"name":"purl: A Simple, Immutable Python URL Class for Clean Manipulation","description":"purl is a Python library offering a simple, immutable URL class designed for easy interrogation and manipulation of URLs. It provides a clean API, supports various Python versions, and includes features like URL template expansion based on RFC 6570. This makes it an excellent tool for handling URLs robustly in your Python projects.","github":"https://github.com/codeinthehole/purl","url":"https://osrepos.com/repo/codeinthehole-purl","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/codeinthehole-purl","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/codeinthehole-purl.md","json":"https://osrepos.com/repo/codeinthehole-purl.json","topics":["Python","URL Parsing","Web Development","Immutable Objects","RFC 6570","URL Manipulation","Python Library"],"keywords":["Python","URL Parsing","Web Development","Immutable Objects","RFC 6570","URL Manipulation","Python Library"],"stars":null,"summary":"purl is a Python library offering a simple, immutable URL class designed for easy interrogation and manipulation of URLs. It provides a clean API, supports various Python versions, and includes features like URL template expansion based on RFC 6570. This makes it an excellent tool for handling URLs robustly in your Python projects.","content":"## Introduction\n\npurl is a powerful yet simple Python library that provides an immutable URL class, offering a clean and intuitive API for interrogating and manipulating URLs. Designed for robustness, purl supports a wide range of Python versions, from 2.7 up to 3.8 and PyPy. A standout feature is its comprehensive support for template URLs, adhering to the specifications of [RFC 6570](http://tools.ietf.org/html/rfc6570 \"RFC 6570 specification\" target=\"_blank\").\n\n## Installation\n\nInstalling purl is straightforward. You can install the stable version from PyPI or the latest development version directly from GitHub.\n\nTo install from PyPI:\n\nbash\npip install purl\n\n\nTo install from GitHub (unstable):\n\nbash\npip install git+git://github.com/codeinthehole/purl.git#egg=purl\n\n\n## Examples\n\npurl's API is designed for ease of use, allowing you to construct, interrogate, and manipulate URL objects efficiently.\n\n### Construction\n\nYou can create `URL` objects from strings, keyword arguments, or by chaining methods:\n\npython\nfrom purl import URL\n\n# String constructor\nfrom_str = URL('https://www.google.com/search?q=testing')\n\n# Keyword constructor\nfrom_kwargs = URL(scheme='https', host='www.google.com', path='/search', query='q=testing')\n\n# Combine methods\nfrom_combo = URL('https://www.google.com').path('search').query_param('q', 'testing')\n\n\nA key aspect of purl is that URL objects are immutable; all methods that modify a URL return a *new* instance.\n\n### Interrogation\n\nAccessing URL components is simple:\n\npython\nu = URL('https://www.google.com/search?q=testing')\nprint(u.scheme())       # 'https'\nprint(u.host())         # 'www.google.com'\nprint(u.path())         # '/search'\nprint(u.query())        # 'q=testing'\nprint(u.query_param('q')) # 'testing'\nprint(u.path_segments())# ('search',)\n\n\n### Manipulation\n\nAccessor methods are overloaded to also act as mutators, returning a new `URL` instance:\n\npython\nu = URL.from_string('https://github.com/codeinthehole')\n\n# Access\nprint(u.path_segment(0)) # 'codeinthehole'\n\n# Mutate (creates a new instance)\nnew_url = u.path_segment(0, 'tangentlabs')\nprint(new_url is u)      # False\nprint(new_url.path_segment(0)) # 'tangentlabs'\n\n\nYou can also build URLs step-by-step:\n\npython\nu = URL().scheme('http').domain('www.example.com').path('/some/path').query_param('q', 'search term')\nprint(u.as_string()) # 'http://www.example.com/some/path?q=search+term'\n\n\npurl also supports URL templates as per RFC 6570:\n\npython\nfrom purl import Template, expand\n\ntpl = Template(\"http://example.com{/list*}\")\nurl = tpl.expand({'list': ['red', 'green', 'blue']})\nprint(url.as_string()) # 'http://example.com/red/green/blue'\n\nexpanded_url = expand(u\"{/list*}\", {'list': ['red', 'green', 'blue']})\nprint(expanded_url) # '/red/green/blue'\n\n\n## Why Use purl?\n\npurl stands out for several reasons, making it an excellent choice for URL handling in Python:\n\n*   **Immutability**: All URL modifications return new instances, ensuring thread-safety and predictability. This also allows `URL` objects to be used as dictionary keys.\n*   **Clean and Consistent API**: The API is intuitive, making it easy to interrogate and manipulate URL components with minimal boilerplate.\n*   **RFC 6570 URL Templates**: Full support for URI templates allows for powerful and flexible URL generation.\n*   **Broad Python Compatibility**: Works across a wide range of Python versions, ensuring compatibility for diverse projects.\n*   **Robustness**: Designed to handle various URL structures and edge cases, providing reliable URL parsing and construction.\n\n## Links\n\n*   **GitHub Repository**: [codeinthehole/purl](https://github.com/codeinthehole/purl \"purl GitHub Repository\" target=\"_blank\")\n*   **Official Documentation**: [purl.readthedocs.org](http://purl.readthedocs.org/en/latest/ \"purl Official Documentation\" target=\"_blank\")\n*   **PyPI Project Page**: [purl on PyPI](https://pypi.org/project/purl/ \"purl PyPI Project Page\" target=\"_blank\")\n*   **RFC 6570 Specification**: [tools.ietf.org/html/rfc6570](http://tools.ietf.org/html/rfc6570 \"RFC 6570 specification\" target=\"_blank\")","metrics":{"detailViews":0,"githubClicks":0},"dates":{"published":null,"modified":"2026-07-27T19:22:31.000Z"}}