location

Models core to the project forge package.

Classes

Location pydantic-model

Bases: BaseModel

The location of a file or directory.

A location supports referencing the file or directory using:

• relative path
• absolute path
• git URL
• git URL plus revision/tag/branch plus path in the repo

When url is specified, the path is relative to the root of the repository.

At least one of path or url must be specified.

Show JSON schema:

{
  "description": "The location of a file or directory.\n\nA location supports referencing the file or directory using:\n\n- relative path\n- absolute path\n- git URL\n- git URL plus revision/tag/branch plus path in the repo\n\nWhen `url` is specified, the `path` is relative to the root of the repository.\n\nAt least one of `path` or `url` must be specified.",
  "properties": {
    "path": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The relative or absolute path to the location.",
      "title": "Path"
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The Git URL to the location.",
      "title": "Url"
    }
  },
  "title": "Location",
  "type": "object"
}

Fields:

• path (Optional[str])
• url (Optional[str])
• _resolved_path (Optional[Path])
• _parsed_url (Optional[ParsedURL])
• parsed_url (Optional[ParsedURL])

Validators:

• _process_url
• _ensure_path_or_url

Attributes

parsed_url pydantic-field

parsed_url: Optional[ParsedURL]

Parse the URL and cache it.

path pydantic-field

path: Optional[str] = None

The relative or absolute path to the location.

url pydantic-field

url: Optional[str] = None

The Git URL to the location.

Functions

__eq__

__eq__(other: object) -> bool

Compare if the objects are the same.

This ignores the private attribute _resolved_path. The locations are equal regardless if the resolve method was previously called.

PARAMETER	DESCRIPTION
other	The other object to compare to. TYPE: object

RETURNS	DESCRIPTION
bool	True if the objects are the same, False otherwise.

from_string classmethod

from_string(location: str) -> Location

Convert a path or URL string into a location.

resolve

resolve(root_path: Optional[Path] = None) -> Path

Find the proper template path for a pattern.

• A relative path is relative to the root path and must exist.
• An absolute path must exist.
• A URL must be to a git repository and a path must exist within the repository.

PARAMETER	DESCRIPTION
root_path	The path to use for resolving relative paths if there is no url. The current working directory is used if None. TYPE: Optional[Path] DEFAULT: None

RAISES	DESCRIPTION
RepoNotFound	If the URL provided returns a 404 error
RepoAuthError	If the URL provided returns a 401 or 403 error
PathNotFound	If the path was not found

RETURNS	DESCRIPTION
Path	The path to the location

Functions

make_absolute

make_absolute(
    path: Union[str, Path], root_path: Optional[Path] = None
) -> Path

Convert relative paths to absolute paths, and return absolute paths unchanged.

PARAMETER	DESCRIPTION
path	The path to convert. TYPE: Union[str, Path]
root_path	The root path to resolve relative paths against. TYPE: Optional[Path] DEFAULT: None

RETURNS	DESCRIPTION
Path	An absolute path.

resolve_url_location

resolve_url_location(location: Location) -> Path

Cache the URL and return the Path to the resolved location.

This downloads the repo into a cache and returns the full path to the template dir.

PARAMETER	DESCRIPTION
location	The location object with a parsed URL TYPE: Location

RAISES	DESCRIPTION
RepoNotFound	If the URL provided returns a 404 error
RepoAuthError	If the URL provided returns a 401 or 403 error
PathNotFound	If the path was not found

RETURNS	DESCRIPTION
Path	Path to the template dir