Git URL Parse

Common errors

• ModuleNotFoundError: No module named 'giturlparse'

  cause The 'giturlparse' package is not installed in your Python environment or is not accessible via your Python path.
  fix Install the package using pip: `pip install giturlparse`

• giturlparse.ParserError: Unable to parse URL: <your_invalid_url>

  cause The input string provided to the `parse` function is not a recognized or valid Git repository URL format.
  fix Ensure the URL string is a correctly formatted Git URL (e.g., HTTPS, SSH, Git protocol) that `giturlparse` can process. Catch `ParserError` to handle invalid inputs gracefully.

• AttributeError: 'NoneType' object has no attribute '...' (e.g., 'some_method')

  cause You are attempting to access a method or attribute on a parsed URL component (like `url2http`) that returned `None` because the corresponding URL type or attribute was not present or couldn't be generated from the parsed Git URL.
  fix Always check if the attribute or method's result is not `None` before attempting to use it, especially for optional components or rewrite functions. For example, `if p.url2http: print(p.url2http)`.

Warnings

• breaking Python 2 support was dropped in version 0.10.0. Installations targeting Python 2 must use versions prior to 0.10.0.
  Fix: Upgrade to Python 3.8+ for versions 0.10.0 and newer, or pin giturlparse to `<0.10.0` if Python 2 is required.
• gotcha The parser logic, especially for non-GitHub platforms (like Bitbucket, GitLab) and URLs containing authentication (username:access_token), has evolved and been refined across multiple versions. Older versions may fail to parse or incorrectly parse newer or specific valid Git URL patterns.
  Fix: Always use the latest available version of `giturlparse` (currently 0.14.0) to ensure the most robust and accurate parsing of various Git URL formats, including those with specific platform nuances or authentication details.
• breaking The `rewrite` method for `GitUrlParsed` objects was introduced in version 0.10.0. Older versions of `giturlparse` (prior to 0.10.0) do not have this method, leading to an `AttributeError` when attempting to use it.
  Fix: Upgrade `giturlparse` to version 0.10.0 or newer to access the `rewrite` method. For these versions, ensure your Python environment is 3.8+ (which is compatible with `python:3.9-slim`).
• breaking The `rewrite` method was removed from `GitUrlParsed` objects in version 0.14.0. Code attempting to use `parsed_url.rewrite(...)` will raise an `AttributeError`.
  Fix: Update code to remove calls to `rewrite` and use alternative methods for URL manipulation, or pin `giturlparse` to a version prior to `0.14.0` (e.g., `giturlparse<0.14.0`).

Install

• pip install giturlparse Install stable version

Imports

• parse

  from giturlparse import parse

• GitUrlParsed

  from giturlparse import GitUrlParsed

  The class returned by the 'parse' function, useful for type hinting.

Quickstart

This quickstart demonstrates parsing different Git URL formats and accessing their components. It also shows how to use the rewrite feature introduced in version 0.14.0 to modify repository details and generate new URLs.

from giturlparse import parse

# Example 1: GitHub SSH URL
url_ssh = parse('git@github.com:nephila/giturlparse.git')
print(f"SSH URL: {url_ssh.url}")
print(f"Owner: {url_ssh.owner}, Name: {url_ssh.name}, Platform: {url_ssh.platform}")

# Example 2: GitLab HTTPS URL with username:token
url_https = parse('https://user:token@gitlab.com/group/repo.git')
print(f"HTTPS URL: {url_https.url}")
print(f"Owner: {url_https.owner}, Name: {url_https.name}, Resource: {url_https.resource}")

# Example 3: Rewriting a URL (feature from v0.14.0)
parsed_url = parse('git@github.com:oldowner/oldrepo.git')
rewritten_url = parsed_url.rewrite(owner='newowner', name='newrepo')
print(f"Rewritten URL (SSH): {rewritten_url.format('ssh')}")
print(f"Rewritten URL (HTTPS): {rewritten_url.format('https')}")