Implementation:Iterative Dvc Fs Dvc Path

Knowledge Sources	Iterative_Dvc
Domains	Filesystem, Path_Abstraction
Last Updated	2026-02-10 10:00 GMT

Overview

DVCPath is a class defined in dvc/fs/dvc_path.py (54 lines) that extends UPath from the upath package. It provides a pathlib.Path-like interface for working with DVCFileSystem, handling the dvc, dvc+http, dvc+https, and dvc+ssh protocol schemes.

from dvc.fs.dvc_path import DVCPath

Source File

Property	Value
File	dvc/fs/dvc_path.py
Lines	54
Class	DVCPath
Extends	UPath (from upath)

Usage Examples

The module docstring provides usage examples:

from upath import UPath

# Local DVC repository
local = UPath("dvc://path/to/local/repo")

# HTTPS-based remote repository
https = UPath("dvc+https://github.com/iterative/example-get-started", rev="main")

# SSH-based remote repository
ssh = UPath("dvc+ssh://git@github.com:iterative/example-get-started.git")

Class: DVCPath

DVCPath extends UPath to normalize DVC-specific URL schemes into the base dvc protocol while preserving the original URL in storage options.

Methods

_transform_init_args (classmethod)

@classmethod
def _transform_init_args(cls, args, protocol, storage_options)

This method is called during path initialization to transform constructor arguments. Its behavior is:

1. If args is empty, defaults to ("/",)
2. If the protocol is one of dvc+http, dvc+https, or dvc+ssh and no url is present in storage_options:
   • Parses the first argument as a URL using urlsplit
   • For SSH: extracts the base URL as netloc + path (e.g., git@github.com:org/repo.git)
   • For HTTP/HTTPS: reconstructs the URL by replacing the compound scheme with the plain protocol
   • Stores the extracted base URL in storage_options["url"]
   • Resets the path args to ("/",) since the URL is now in storage options
3. Delegates to the parent _transform_init_args with the normalized "dvc" protocol

__str__

def __str__(self) -> str

Overrides string representation. If the storage options contain a url, replaces the generic dvc:// prefix with dvc+{url} to reconstruct the original compound URI. Otherwise, falls back to the default UPath.__str__().

with_segments

def with_segments(self, *pathsegments)

Overrides the path segment joining behavior to cache the filesystem instance. Since DVCFileSystem does not cache its own filesystem object, this method stores it on the new path object via obj._fs_cached. This avoids re-instantiating the filesystem on every joinpath operation.

Protocol Handling

Protocol	URL Extraction	Example
dvc	Direct (no transformation)	dvc://path/to/local/repo
dvc+http	Strips dvc+ prefix from scheme	dvc+http://example.com/repo
dvc+https	Strips dvc+ prefix from scheme	dvc+https://github.com/org/repo
dvc+ssh	Uses netloc + path format	dvc+ssh://git@host:org/repo.git

Key Dependencies

Module	Usage
upath.UPath	Base class providing pathlib-like interface for remote filesystems
urllib.parse.urlsplit	Parsing compound DVC URLs into components

See Also

• Implementation:Dependency_Repo -- Uses DVCFileSystem for cross-repo access