{"id":6941,"library":"urlobject","title":"URLObject","description":"URLObject is a utility class for manipulating URLs in Python. The latest version, 3.0.0, aims for a clearer API by focusing on explicit method names rather than relying heavily on operator overrides, building upon its predecessors. It provides an immutable object-oriented interface for parsing, constructing, and modifying URLs and their components. It is actively maintained with a recent release.","status":"active","version":"3.0.0","language":"python","source_language":"en","source_url":"http://github.com/zacharyvoase/urlobject","tags":["url","uri","manipulation","parsing","immutable"],"install":[{"cmd":"pip install urlobject","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"URLObject","correct":"from urlobject import URLObject"}],"quickstart":{"code":"import os\nfrom urlobject import URLObject\n\n# Create a URLObject from a string\nurl = URLObject(\"https://github.com/zacharyvoase/urlobject?topic=python&q=docs#api-reference\")\nprint(f\"Original URL: {url}\")\n\n# URLObject instances are immutable; methods return new objects\nmodified_url = (\n    url.with_scheme('http')\n    .with_hostname('example.com')\n    .add_query_param('lang', 'en')\n    .without_fragment()\n)\nprint(f\"Modified URL: {modified_url}\")\n\n# Access individual components\nprint(f\"Scheme: {modified_url.scheme}\")\nprint(f\"Hostname: {modified_url.hostname}\")\nprint(f\"Path: {modified_url.path}\")\nprint(f\"Query params: {modified_url.query_list_multidict()}\")\n\n# Example with authentication (use environment variables for sensitive data)\nauth_url = URLObject(\"https://api.example.com/data\").with_auth(\n    os.environ.get('API_USERNAME', 'your_username'),\n    os.environ.get('API_PASSWORD', 'your_password')\n)\nprint(f\"URL with auth (sensitive parts hidden): {auth_url.without_auth()}\")","lang":"python","description":"Demonstrates creating a URLObject, immutably modifying its components, accessing properties, and an example of handling authentication details using environment variables."},"warnings":[{"fix":"Review your code and replace operator overloads with explicit method calls as described in the library's documentation for version 3.x. For example, use `url.add_path('segment')` instead of `url + 'segment'`.","message":"Major API changes occurred between `urlobject` 2.x and 3.x. Version 3.x shifts focus to 'proper method names over operator overrides'. Code relying on operator overloading (e.g., `url + '/path'`) from older versions will break and needs to be migrated to explicit methods like `.add_path()`, `.with_query()`, etc.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Always assign the return value of modification methods to a variable: `my_new_url = original_url.with_scheme('https')`.","message":"URLObject instances are immutable. All methods that 'modify' a URLObject (e.g., `with_scheme()`, `add_query_param()`, `without_fragment()`) return a *new* URLObject instance with the applied changes, leaving the original object untouched. Forgetting to assign the result of these methods will lead to no changes being observed.","severity":"gotcha","affected_versions":"All"},{"fix":"Store sensitive credentials in environment variables and access them using `os.environ.get('YOUR_ENV_VAR', 'default_value')` when constructing URLs with authentication.","message":"When handling sensitive information like API keys or passwords in URLs, avoid hardcoding them directly in your code. Using `os.environ.get()` is a safer practice to retrieve credentials from environment variables.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'3.0.0':15 'activ':57 'aim':16 'api':20 'build':34 'class':6 'clearer':19 'compon':54 'construct':48 'explicit':24 'focus':22 'heavili':30 'immut':41,67 'interfac':45 'latest':13 'maintain':58 'manipul':8,65 'method':25 'modifi':50 'name':26 'object':43 'object-ori':42 'oper':32 'orient':44 'overrid':33 'pars':47,66 'predecessor':37 'provid':39 'python':11 'rather':27 'recent':61 'releas':62 'reli':29 'upon':35 'uri':64 'url':9,51,63 'urlobject':1,2 'util':5 'version':14","created_at":"2026-04-15T18:49:37.335727+00:00","updated_at":"2026-04-17T00:00:54.551974+00:00","problems":[{"fix":"Use the `join()` method for concatenating URL segments or other URLs: `URLObject('http://example.com/base').join('segment')`","cause":"The `+` operator for concatenating URL paths was removed in `urlobject` version 3.0.0, which prioritizes explicit method names over operator overloading.","error":"TypeError: unsupported operand type(s) for +: 'URLObject' and 'str'"},{"fix":"Use the `query_params` property to access query parameters (read-only dict) or `add_query_params()` to modify them: `url_obj.add_query_params({'param': 'value'})` or `print(url_obj.query_params.get('param'))`","cause":"The `q` attribute for accessing query parameters was removed in `urlobject` version 3.0.0; the API was revised for clarity.","error":"AttributeError: 'URLObject' object has no attribute 'q'"},{"fix":"Use the `path_parts` property to get the path segments as a list, and `replace_path_parts()` to modify them: `url_obj.replace_path_parts(['new', 'path', 'segments'])` or `print(url_obj.path_parts)`","cause":"The `path` attribute (a list of strings) was removed in `urlobject` version 3.0.0 in favor of a clearer API.","error":"AttributeError: 'URLObject' object has no attribute 'path'"},{"fix":"Import the `URLObject` class and call `parse` on it: `from urlobject import URLObject; URLObject.parse('http://example.com')`","cause":"The `parse` method is a static method of the `URLObject` class, not a top-level function directly available from the `urlobject` module.","error":"AttributeError: module 'urlobject' has no attribute 'parse'"},{"fix":"Add an import statement for the `URLObject` class at the beginning of your script: `from urlobject import URLObject`","cause":"The `URLObject` class was used in the code without being explicitly imported from the `urlobject` library first.","error":"NameError: name 'URLObject' is not defined"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/zacharyvoase/urlobject","docs":null,"changelog":null,"pypi":"https://pypi.org/project/urlobject/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}