wandb 0.18.5__py3-none-any.whl → 0.18.7__py3-none-any.whl

wandb/sdk/artifacts/artifact_manifest.py

@@ -48,18 +48,19 @@ class ArtifactManifest:
     def digest(self) -> HexMD5:
         raise NotImplementedError
 
-    def add_entry(self, entry: ArtifactManifestEntry) -> None:
-        if (
-            entry.path in self.entries
-            and entry.digest != self.entries[entry.path].digest
-        ):
-            raise ValueError("Cannot add the same path twice: {}".format(entry.path))
-        self.entries[entry.path] = entry
+    def add_entry(self, entry: ArtifactManifestEntry, overwrite: bool = False) -> None:
+        path = entry.path
+        if not overwrite:
+            prev_entry = self.entries.get(path)
+            if prev_entry and (entry.digest != prev_entry.digest):
+                raise ValueError(f"Cannot add the same path twice: {path!r}")
+        self.entries[path] = entry
 
     def remove_entry(self, entry: ArtifactManifestEntry) -> None:
-        if entry.path not in self.entries:
+        try:
+            del self.entries[entry.path]
+        except LookupError:
             raise FileNotFoundError(f"Cannot remove missing entry: '{entry.path}'")
-        del self.entries[entry.path]
 
     def get_entry_by_path(self, path: str) -> ArtifactManifestEntry | None:
         return self.entries.get(path)

wandb/sdk/artifacts/artifact_manifest_entry.py

@@ -133,7 +133,7 @@ class ArtifactManifestEntry:
     ) -> FilePathStr:
         """Download this artifact entry to the specified root path.
 
-        Arguments:
+        Args:
             root: (str, optional) The root path in which to download this
                 artifact entry. Defaults to the artifact's root.
 

wandb/sdk/artifacts/storage_handlers/azure_handler.py

@@ -28,6 +28,9 @@ class AzureHandler(StorageHandler):
             ".blob.core.windows.net"
         )
 
+    def __init__(self, scheme: str | None = None) -> None:
+        self._cache = get_artifact_file_cache()
+
     def load_path(
         self,
         manifest_entry: ArtifactManifestEntry,
@@ -37,7 +40,7 @@ class AzureHandler(StorageHandler):
         if not local:
             return manifest_entry.ref
 
-        path, hit, cache_open = get_artifact_file_cache().check_etag_obj_path(
+        path, hit, cache_open = self._cache.check_etag_obj_path(
             URIStr(manifest_entry.ref),
             ETag(manifest_entry.digest),
             manifest_entry.size or 0,
@@ -136,10 +139,11 @@ class AzureHandler(StorageHandler):
             name_starts_with=f"{blob_name}/"
         ):
             if len(entries) >= max_objects:
-                raise ValueError(
-                    f"Exceeded {max_objects} objects tracked, pass max_objects to "
-                    f"add_reference"
+                wandb.termwarn(
+                    f"Found more than {max_objects} objects under path, limiting upload "
+                    f"to {max_objects} objects. Increase max_objects to upload more"
                 )
+                break
             if not self._is_directory_stub(blob_properties):
                 suffix = PurePosixPath(blob_properties.name).relative_to(blob_name)
                 entries.append(
@@ -151,6 +155,7 @@ class AzureHandler(StorageHandler):
                         ),
                     )
                 )
+
         return entries
 
     def _get_module(self, name: str) -> ModuleType:

wandb/sdk/artifacts/storage_handlers/gcs_handler.py

@@ -24,8 +24,6 @@ if TYPE_CHECKING:
 class _GCSIsADirectoryError(Exception):
     """Raised when we try to download a GCS folder."""
 
-    pass
-
 
 class GCSHandler(StorageHandler):
     _client: gcs_module.client.Client | None
@@ -169,7 +167,7 @@ class GCSHandler(StorageHandler):
     ) -> ArtifactManifestEntry:
         """Create an ArtifactManifestEntry from a GCS object.
 
-        Arguments:
+        Args:
             obj: The GCS object
             path: The GCS-style path (e.g.: "gs://bucket/file.txt")
             name: The user assigned name, or None if not specified

wandb/sdk/artifacts/storage_handlers/s3_handler.py

@@ -243,7 +243,7 @@ class S3Handler(StorageHandler):
     ) -> ArtifactManifestEntry:
         """Create an ArtifactManifestEntry from an S3 object.
 
-        Arguments:
+        Args:
             obj: The S3 object
             path: The S3-style path (e.g.: "s3://bucket/file.txt")
             name: The user assigned name, or None if not specified

wandb/sdk/artifacts/storage_handlers/wb_artifact_handler.py

@@ -49,7 +49,7 @@ class WBArtifactHandler(StorageHandler):
 
         Download the referenced artifact; create and return a new symlink to the caller.
 
-        Arguments:
+        Args:
             manifest_entry (ArtifactManifestEntry): The index entry to load
 
         Returns:
@@ -89,7 +89,7 @@ class WBArtifactHandler(StorageHandler):
 
         Recursively resolves the reference until the result is a concrete asset.
 
-        Arguments:
+        Args:
             artifact: The artifact doing the storing path (str): The path to store name
             (str): If specified, the logical name that should map to `path`
 

wandb/sdk/artifacts/storage_handlers/wb_local_artifact_handler.py

@@ -46,7 +46,7 @@ class WBLocalArtifactHandler(StorageHandler):
     ) -> Sequence[ArtifactManifestEntry]:
         """Store the file or directory at the given path within the specified artifact.
 
-        Arguments:
+        Args:
             artifact: The artifact doing the storing
             path (str): The path to store
             name (str): If specified, the logical name that should map to `path`

wandb/sdk/backend/backend.py

@@ -203,7 +203,6 @@ class Backend:
 
     def server_status(self) -> None:
         """Report server status."""
-        pass
 
     def cleanup(self) -> None:
         # TODO: make _done atomic

wandb/sdk/data_types/audio.py

@@ -13,7 +13,7 @@ from .base_types.media import BatchableMedia
 class Audio(BatchableMedia):
     """Wandb class for audio clips.
 
-    Arguments:
+    Args:
         data_or_path: (string or numpy array) A path to an audio file
             or a numpy array of audio data.
         sample_rate: (int) Sample rate, required when passing in raw

wandb/sdk/data_types/base_types/media.py

@@ -24,9 +24,75 @@ if TYPE_CHECKING:  # pragma: no cover
 SYS_PLATFORM = platform.system()
 
 
+def check_windows_valid_filename(path: Union[int, str]) -> bool:
+    r"""Verify that the given path does not contain any invalid characters for a Windows filename.
+
+    Windows filenames cannot contain the following characters:
+    < > : " \ / | ? *
+
+    For more details, refer to the official documentation:
+    https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
+
+    Args:
+        path: The file path to check, which can be either an integer or a string.
+
+    Returns:
+        bool: True if the path does not contain any invalid characters, False otherwise.
+    """
+    return not bool(re.search(r'[<>:"\\?*]', path))  # type: ignore
+
+
 def _wb_filename(
     key: Union[str, int], step: Union[str, int], id: Union[str, int], extension: str
 ) -> str:
+    r"""Generates a safe filename/path for storing media files, using the provided key, step, and id.
+
+    The filename is made safe by:
+    1. Removing any leading slashes to prevent writing to absolute paths
+    2. Replacing '.' and '..' with underscores to prevent directory traversal attacks
+
+    If the key contains slashes (e.g. 'images/cats/fluffy.jpg'), subdirectories will be created:
+        media/
+          images/
+            cats/
+              fluffy.jpg_step_id.ext
+
+    Args:
+        key: Name/path for the media file
+        step: Training step number
+        id: Unique identifier
+        extension: File extension (e.g. '.jpg', '.mp3')
+
+    Returns:
+        A sanitized filename string in the format: key_step_id.extension
+
+    Raises:
+        ValueError: If running on Windows and the key contains invalid filename characters
+                   (\\, :, *, ?, ", <, >, |)
+    """
+    if SYS_PLATFORM == "Windows" and not check_windows_valid_filename(key):
+        raise ValueError(
+            f'Media {key} is invalid. Please remove invalid filename characters (\\, :, *, ?, ", <, >, |)'
+        )
+
+    # On Windows, convert forward slashes to backslashes.
+    # This ensures that the key is a valid filename on Windows.
+    if SYS_PLATFORM == "Windows":
+        key = str(key).replace("/", os.sep)
+
+    # Avoid writing to absolute paths by striping any leading slashes.
+    # The key has already been validated for windows operating systems in util.check_windows_valid_filename
+    # This ensures the key does not contain invalid characters for windows, such as '\' or ':'.
+    # So we can check only for '/' in the key.
+    key = str(key).lstrip(os.sep)
+
+    # Avoid directory traversal by replacing dots with underscores.
+    keys = key.split(os.sep)
+    keys = [k.replace(".", "_") if k in (os.curdir, os.pardir) else k for k in keys]
+
+    # Recombine the key into a relative path.
+    key = os.sep.join(keys)
+
     return f"{str(key)}_{str(step)}_{str(id)}{extension}"
 
 
@@ -100,11 +166,6 @@ class Media(WBValue):
         """
         assert self.file_is_set(), "bind_to_run called before _set_file"
 
-        if SYS_PLATFORM == "Windows" and not util.check_windows_valid_filename(key):
-            raise ValueError(
-                f"Media {key} is invalid. Please remove invalid filename characters"
-            )
-
         # The following two assertions are guaranteed to pass
         # by definition file_is_set, but are needed for
         # mypy to understand that these are strings below.

wandb/sdk/data_types/base_types/wb_value.py

@@ -1,5 +1,6 @@
 from typing import TYPE_CHECKING, Any, ClassVar, Dict, List, Optional, Type, Union
 
+import wandb
 from wandb import util
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -13,16 +14,25 @@ if TYPE_CHECKING:  # pragma: no cover
 def _server_accepts_client_ids() -> bool:
     from wandb.util import parse_version
 
-    # First, if we are offline, assume the backend server cannot
-    # accept client IDs. Unfortunately, this is the best we can do
-    # until we are sure that all local versions are > "0.11.0" max_cli_version.
-    # The practical implication is that tables logged in offline mode
-    # will not show up in the workspace (but will still show up in artifacts). This
-    # means we never lose data, and we can still view using weave. If we decided
-    # to use client ids in offline mode, then the manifests and artifact data
-    # would never be resolvable and would lead to failed uploads. Our position
-    # is to never lose data - and instead take the tradeoff in the UI.
-    if util._is_offline():
+    # There are versions of W&B Server that cannot accept client IDs. Those versions of
+    # the backend have a max_cli_version of less than "0.11.0." If the backend cannot
+    # accept client IDs, manifests and artifact data would never be resolvable and lead
+    # to failed uploads. Our position in 2021/06/29 was to never lose data - and instead take the
+    # tradeoff in the UI. The results in tables not displaying media correctly, but
+    # the table can still be accessed via the .artifact op.
+    #
+    # The latest SDK version that is < "0.11.0" was released on 2021/06/29.
+    # AS OF NOW, 2024/11/06, we assume that all customer's server deployments accept
+    # client IDs.
+    #
+    # If there are any users with issues on an older backend, customers can disable the
+    # setting `allow_offline_artifacts` to revert the SDK's behavior back to not
+    # using client IDs in offline mode.
+    if (
+        util._is_offline()
+        and wandb.run
+        and not wandb.run.settings.allow_offline_artifacts
+    ):
         return False
 
     # If the script is online, request the max_cli_version and ensure the server

wandb/sdk/data_types/bokeh.py

@@ -13,7 +13,7 @@ from .base_types.media import Media
 class Bokeh(Media):
     """Wandb class for Bokeh plots.
 
-    Arguments:
+    Args:
         val: Bokeh plot
     """
 

wandb/sdk/data_types/helper_types/bounding_boxes_2d.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:  # pragma: no cover
 class BoundingBoxes2D(JSONMetadata):
     """Format images with 2D bounding box overlays for logging to W&B.
 
-    Arguments:
+    Args:
         val: (dictionary) A dictionary of the following form:
             box_data: (list of dictionaries) One dictionary for each bounding box, containing:
                 position: (dictionary) the position and size of the bounding box, in one of two formats

wandb/sdk/data_types/helper_types/image_mask.py

@@ -18,7 +18,7 @@ if TYPE_CHECKING:  # pragma: no cover
 class ImageMask(Media):
     """Format image masks or overlays for logging to W&B.
 
-    Arguments:
+    Args:
         val: (dictionary)
             One of these two keys to represent the image:
                 mask_data : (2D numpy array) The mask containing an integer class label
@@ -117,7 +117,7 @@ class ImageMask(Media):
     def __init__(self, val: dict, key: str) -> None:
         """Initialize an ImageMask object.
 
-        Arguments:
+        Args:
             val: (dictionary) One of these two keys to represent the image:
                 mask_data : (2D numpy array) The mask containing an integer class label
                     for each pixel in the image

wandb/sdk/data_types/histogram.py

@@ -33,7 +33,7 @@ class Histogram(WBValue):
         wandb.Histogram(np_histogram=hist)
         ```
 
-    Arguments:
+    Args:
         sequence: (array_like) input data for histogram
         np_histogram: (numpy histogram) alternative input of a precomputed histogram
         num_bins: (int) Number of bins for the histogram.  The default number of bins

wandb/sdk/data_types/html.py

@@ -18,7 +18,7 @@ if TYPE_CHECKING:  # pragma: no cover
 class Html(BatchableMedia):
     """Wandb class for arbitrary html.
 
-    Arguments:
+    Args:
         data: (string or io object) HTML to display in wandb
         inject: (boolean) Add a stylesheet to the HTML object.  If set
             to False the HTML will pass through unchanged.

wandb/sdk/data_types/image.py

@@ -65,7 +65,7 @@ def _server_accepts_artifact_path() -> bool:
 class Image(BatchableMedia):
     """Format images for logging to W&B.
 
-    Arguments:
+    Args:
         data_or_path: (numpy array, string, io) Accepts numpy array of
             image data, or a PIL image. The class attempts to infer
             the data format and converts it.

wandb/sdk/data_types/molecule.py

@@ -25,7 +25,7 @@ if TYPE_CHECKING:  # pragma: no cover
 class Molecule(BatchableMedia):
     """Wandb class for 3D Molecular data.
 
-    Arguments:
+    Args:
         data_or_path: (string, io)
             Molecule can be initialized from a file name or an io object.
         caption: (string)
@@ -106,7 +106,7 @@ class Molecule(BatchableMedia):
     ) -> "Molecule":
         """Convert RDKit-supported file/object types to wandb.Molecule.
 
-        Arguments:
+        Args:
             data_or_path: (string, rdkit.Chem.rdchem.Mol)
                 Molecule can be initialized from a file name or an rdkit.Chem.rdchem.Mol object.
             caption: (string)
@@ -173,7 +173,7 @@ class Molecule(BatchableMedia):
     ) -> "Molecule":
         """Convert SMILES string to wandb.Molecule.
 
-        Arguments:
+        Args:
             data: (string)
                 SMILES string.
             caption: (string)

wandb/sdk/data_types/object_3d.py

@@ -190,7 +190,7 @@ def box3d(
 class Object3D(BatchableMedia):
     """Wandb class for 3D point clouds.
 
-    Arguments:
+    Args:
         data_or_path: (numpy array, string, io)
             Object3D can be initialized from a file or a numpy array.
 
@@ -341,7 +341,7 @@ class Object3D(BatchableMedia):
     ) -> "Object3D":
         """Initializes Object3D from a file or stream.
 
-        Arguments:
+        Args:
             data_or_path (Union["TextIO", str]): A path to a file or a `TextIO` stream.
             file_type (str): Specifies the data format passed to `data_or_path`. Required when `data_or_path` is a
                 `TextIO` stream. This parameter is ignored if a file path is provided. The type is taken from the file extension.
@@ -356,7 +356,7 @@ class Object3D(BatchableMedia):
     def from_numpy(cls, data: "np.ndarray") -> "Object3D":
         """Initializes Object3D from a numpy array.
 
-        Arguments:
+        Args:
             data (numpy array): Each entry in the array will
                 represent one point in the point cloud.
 
@@ -394,7 +394,7 @@ class Object3D(BatchableMedia):
     ) -> "Object3D":
         """Initializes Object3D from a python object.
 
-        Arguments:
+        Args:
             points (Sequence["Point"]): The points in the point cloud.
             boxes (Sequence["Box3D"]): 3D bounding boxes for labeling the point cloud. Boxes
             are displayed in point cloud visualizations.

wandb/sdk/data_types/plotly.py

@@ -33,7 +33,7 @@ if TYPE_CHECKING:  # pragma: no cover
 class Plotly(Media):
     """Wandb class for plotly plots.
 
-    Arguments:
+    Args:
         val: matplotlib or plotly figure
     """
 

wandb/sdk/data_types/saved_model.py

@@ -232,7 +232,6 @@ class _SavedModel(WBValue, Generic[SavedModelObjType]):
         except Exception as e:
             if DEBUG_MODE:
                 print(f"{cls}._maybe_init({obj_or_path}) failed: {e}")
-            pass
 
         for child_cls in cls.__subclasses__():
             maybe_instance = child_cls._maybe_init(obj_or_path, **kwargs)

wandb/sdk/data_types/table.py

@@ -191,7 +191,7 @@ class Table(Media):
     This class is the primary class used to generate the Table Visualizer
     in the UI: https://docs.wandb.ai/guides/data-vis/tables.
 
-    Arguments:
+    Args:
         columns: (List[str]) Names of the columns in the table.
             Defaults to ["Input", "Output", "Expected"].
         data: (List[List[any]]) 2D row-oriented array of values.
@@ -318,7 +318,7 @@ class Table(Media):
         This can be one of the normal python classes, an internal W&B type, or an
         example object, like an instance of wandb.Image or wandb.Classes.
 
-        Arguments:
+        Args:
             col_name: (str) - The name of the column to cast.
             dtype: (class, wandb.wandb_sdk.interface._dtypes.Type, any) - The target dtype.
             optional: (bool) - If the column should allow Nones.
@@ -704,7 +704,7 @@ class Table(Media):
         If the state has been updated since the last update, wraps the data
         appropriately in the Key classes.
 
-        Arguments:
+        Args:
             force_last: (bool) Wraps the last column of data even if there
                 are no key updates.
         """
@@ -748,7 +748,7 @@ class Table(Media):
     def _apply_key_updates(self, only_last=False):
         """Appropriately wraps the underlying data in special Key classes.
 
-        Arguments:
+        Args:
             only_last: only apply the updates to the last row (used for performance when
             the caller knows that the only new data is the last row and no updates were
             applied to the column types)
@@ -797,7 +797,7 @@ class Table(Media):
     def add_column(self, name, data, optional=False):
         """Adds a column of data to the table.
 
-        Arguments:
+        Args:
             name: (str) - the unique name of the column
             data: (list | np.array) - a column of homogeneous data
             optional: (bool) - if null-like values are permitted
@@ -838,7 +838,7 @@ class Table(Media):
     def get_column(self, name, convert_to=None):
         """Retrieves a column from the table and optionally converts it to a NumPy object.
 
-        Arguments:
+        Args:
             name: (str) - the name of the column
             convert_to: (str, optional)
                 - "numpy": will convert the underlying data to numpy object
@@ -1015,7 +1015,7 @@ class PartitionedTable(Media):
 class JoinedTable(Media):
     """Join two tables for visualization in the Artifact UI.
 
-    Arguments:
+    Args:
         table1 (str, wandb.Table, ArtifactManifestEntry):
             the path to a wandb.Table in an artifact, the table object, or ArtifactManifestEntry
         table2 (str, wandb.Table):

wandb/sdk/data_types/trace_tree.py

@@ -80,7 +80,7 @@ class Span:
 class WBTraceTree(Media):
     """Media object for trace tree data.
 
-    Arguments:
+    Args:
         root_span (Span): The root span of the trace tree.
         model_dict (dict, optional): A dictionary containing the model dump.
             NOTE: model_dict is a completely-user-defined dict. The UI will render

wandb/sdk/data_types/video.py

@@ -49,7 +49,7 @@ def write_gif_with_image_io(
 class Video(BatchableMedia):
     """Format a video for logging to W&B.
 
-    Arguments:
+    Args:
         data_or_path: (numpy array, string, io)
             Video can be initialized with a path to a file or an io object.
             The format must be "gif", "mp4", "webm" or "ogg".
@@ -103,10 +103,11 @@ class Video(BatchableMedia):
             )
 
         if isinstance(data_or_path, (BytesIO, str)) and fps:
-            wandb.termwarn(
+            msg = (
                 "`fps` argument does not affect the frame rate of the video "
-                + "when providing a file path or raw bytes."
+                "when providing a file path or raw bytes."
             )
+            wandb.termwarn(msg)
 
         if isinstance(data_or_path, BytesIO):
             filename = os.path.join(

wandb/sdk/interface/interface_queue.py

@@ -8,7 +8,6 @@ import logging
 from multiprocessing.process import BaseProcess
 from typing import TYPE_CHECKING, Optional
 
-from ..lib import tracelog
 from ..lib.mailbox import Mailbox
 from .interface_shared import InterfaceShared
 from .router_queue import MessageQueueRouter
@@ -37,10 +36,6 @@ class InterfaceQueue(InterfaceShared):
     ) -> None:
         self.record_q = record_q
         self.result_q = result_q
-        if self.record_q:
-            tracelog.annotate_queue(self.record_q, "record_q")
-        if self.result_q:
-            tracelog.annotate_queue(self.result_q, "result_q")
         super().__init__(process=process, process_check=process_check, mailbox=mailbox)
 
     def _init_router(self) -> None:
@@ -55,5 +50,4 @@ class InterfaceQueue(InterfaceShared):
         if local:
             record.control.local = local
         if self.record_q:
-            tracelog.log_message_queue(record, self.record_q)
             self.record_q.put(record)

wandb/sdk/interface/router.py

@@ -10,7 +10,7 @@ import uuid
 from abc import abstractmethod
 from typing import TYPE_CHECKING, Dict, Optional
 
-from ..lib import mailbox, tracelog
+from ..lib import mailbox
 from .message_future import MessageFuture
 
 if TYPE_CHECKING:
@@ -25,8 +25,6 @@ logger = logging.getLogger("wandb")
 class MessageRouterClosedError(Exception):
     """Router has been closed."""
 
-    pass
-
 
 class MessageFutureObject(MessageFuture):
     def __init__(self) -> None:
@@ -110,7 +108,6 @@ class MessageRouter:
             # TODO (cvp): saw this in tests, seemed benign enough to ignore, but
             # could point to other issues.
             if msg.uuid != "":
-                tracelog.log_message_assert(msg)
                 logger.warning(
                     "No listener found for msg with uuid %s (%s)", msg.uuid, msg
                 )

wandb/sdk/interface/router_queue.py

@@ -7,7 +7,6 @@ Router to manage responses from a queue.
 import queue
 from typing import TYPE_CHECKING, Optional
 
-from ..lib import tracelog
 from ..lib.mailbox import Mailbox
 from .router import MessageRouter
 
@@ -36,9 +35,7 @@ class MessageQueueRouter(MessageRouter):
             msg = self._response_queue.get(timeout=1)
         except queue.Empty:
             return None
-        tracelog.log_message_dequeue(msg, self._response_queue)
         return msg
 
     def _send_message(self, record: "pb.Record") -> None:
-        tracelog.log_message_queue(record, self._request_queue)
         self._request_queue.put(record)

wandb/sdk/interface/router_relay.py

@@ -6,7 +6,6 @@ Router to manage responses from a queue with relay.
 
 from typing import TYPE_CHECKING
 
-from ..lib import tracelog
 from ..lib.mailbox import Mailbox
 from .router_queue import MessageQueueRouter
 
@@ -33,7 +32,6 @@ class MessageRelayRouter(MessageQueueRouter):
 
     def _handle_msg_rcv(self, msg: "pb.Result") -> None:
         if msg.control.relay_id:
-            tracelog.log_message_queue(msg, self._relay_queue)
             self._relay_queue.put(msg)
             return
         super()._handle_msg_rcv(msg)

wandb/sdk/internal/datastore.py

@@ -277,7 +277,7 @@ class DataStore:
     def write(self, obj: "Record") -> Tuple[int, int, int]:
         """Write a protocol buffer.
 
-        Arguments:
+        Args:
             obj: Protocol buffer to write.
 
         Returns:

wandb/sdk/internal/file_pusher.py

@@ -129,7 +129,7 @@ class FilePusher:
     def file_changed(self, save_name: LogicalPath, path: str, copy: bool = True):
         """Tell the file pusher that a file's changed and should be uploaded.
 
-        Arguments:
+        Args:
             save_name: string logical location of the file relative to the run
                 directory.
             path: actual string path of the file to upload on the filesystem.