| | """ |
| | This module contains SMBFileSystem class responsible for handling access to |
| | Windows Samba network shares by using package smbprotocol |
| | """ |
| |
|
| | import datetime |
| | import uuid |
| | from stat import S_ISDIR, S_ISLNK |
| |
|
| | import smbclient |
| |
|
| | from .. import AbstractFileSystem |
| | from ..utils import infer_storage_options |
| |
|
| | |
| |
|
| |
|
| | class SMBFileSystem(AbstractFileSystem): |
| | """Allow reading and writing to Windows and Samba network shares. |
| | |
| | When using `fsspec.open()` for getting a file-like object the URI |
| | should be specified as this format: |
| | ``smb://workgroup;user:password@server:port/share/folder/file.csv``. |
| | |
| | Example:: |
| | |
| | >>> import fsspec |
| | >>> with fsspec.open( |
| | ... 'smb://myuser:mypassword@myserver.com/' 'share/folder/file.csv' |
| | ... ) as smbfile: |
| | ... df = pd.read_csv(smbfile, sep='|', header=None) |
| | |
| | Note that you need to pass in a valid hostname or IP address for the host |
| | component of the URL. Do not use the Windows/NetBIOS machine name for the |
| | host component. |
| | |
| | The first component of the path in the URL points to the name of the shared |
| | folder. Subsequent path components will point to the directory/folder/file. |
| | |
| | The URL components ``workgroup`` , ``user``, ``password`` and ``port`` may be |
| | optional. |
| | |
| | .. note:: |
| | |
| | For working this source require `smbprotocol`_ to be installed, e.g.:: |
| | |
| | $ pip install smbprotocol |
| | # or |
| | # pip install smbprotocol[kerberos] |
| | |
| | .. _smbprotocol: https://github.com/jborean93/smbprotocol#requirements |
| | |
| | Note: if using this with the ``open`` or ``open_files``, with full URLs, |
| | there is no way to tell if a path is relative, so all paths are assumed |
| | to be absolute. |
| | """ |
| |
|
| | protocol = "smb" |
| |
|
| | |
| | def __init__( |
| | self, |
| | host, |
| | port=None, |
| | username=None, |
| | password=None, |
| | timeout=60, |
| | encrypt=None, |
| | share_access=None, |
| | **kwargs, |
| | ): |
| | """ |
| | You can use _get_kwargs_from_urls to get some kwargs from |
| | a reasonable SMB url. |
| | |
| | Authentication will be anonymous or integrated if username/password are not |
| | given. |
| | |
| | Parameters |
| | ---------- |
| | host: str |
| | The remote server name/ip to connect to |
| | port: int or None |
| | Port to connect with. Usually 445, sometimes 139. |
| | username: str or None |
| | Username to connect with. Required if Kerberos auth is not being used. |
| | password: str or None |
| | User's password on the server, if using username |
| | timeout: int |
| | Connection timeout in seconds |
| | encrypt: bool |
| | Whether to force encryption or not, once this has been set to True |
| | the session cannot be changed back to False. |
| | share_access: str or None |
| | Specifies the default access applied to file open operations |
| | performed with this file system object. |
| | This affects whether other processes can concurrently open a handle |
| | to the same file. |
| | |
| | - None (the default): exclusively locks the file until closed. |
| | - 'r': Allow other handles to be opened with read access. |
| | - 'w': Allow other handles to be opened with write access. |
| | - 'd': Allow other handles to be opened with delete access. |
| | """ |
| | super().__init__(**kwargs) |
| | self.host = host |
| | self.port = port |
| | self.username = username |
| | self.password = password |
| | self.timeout = timeout |
| | self.encrypt = encrypt |
| | self.temppath = kwargs.pop("temppath", "") |
| | self.share_access = share_access |
| | self._connect() |
| |
|
| | @property |
| | def _port(self): |
| | return 445 if self.port is None else self.port |
| |
|
| | def _connect(self): |
| | smbclient.register_session( |
| | self.host, |
| | username=self.username, |
| | password=self.password, |
| | port=self._port, |
| | encrypt=self.encrypt, |
| | connection_timeout=self.timeout, |
| | ) |
| |
|
| | @classmethod |
| | def _strip_protocol(cls, path): |
| | return infer_storage_options(path)["path"] |
| |
|
| | @staticmethod |
| | def _get_kwargs_from_urls(path): |
| | |
| | out = infer_storage_options(path) |
| | out.pop("path", None) |
| | out.pop("protocol", None) |
| | return out |
| |
|
| | def mkdir(self, path, create_parents=True, **kwargs): |
| | wpath = _as_unc_path(self.host, path) |
| | if create_parents: |
| | smbclient.makedirs(wpath, exist_ok=False, port=self._port, **kwargs) |
| | else: |
| | smbclient.mkdir(wpath, port=self._port, **kwargs) |
| |
|
| | def makedirs(self, path, exist_ok=False): |
| | if _share_has_path(path): |
| | wpath = _as_unc_path(self.host, path) |
| | smbclient.makedirs(wpath, exist_ok=exist_ok, port=self._port) |
| |
|
| | def rmdir(self, path): |
| | if _share_has_path(path): |
| | wpath = _as_unc_path(self.host, path) |
| | smbclient.rmdir(wpath, port=self._port) |
| |
|
| | def info(self, path, **kwargs): |
| | wpath = _as_unc_path(self.host, path) |
| | stats = smbclient.stat(wpath, port=self._port, **kwargs) |
| | if S_ISDIR(stats.st_mode): |
| | stype = "directory" |
| | elif S_ISLNK(stats.st_mode): |
| | stype = "link" |
| | else: |
| | stype = "file" |
| | res = { |
| | "name": path + "/" if stype == "directory" else path, |
| | "size": stats.st_size, |
| | "type": stype, |
| | "uid": stats.st_uid, |
| | "gid": stats.st_gid, |
| | "time": stats.st_atime, |
| | "mtime": stats.st_mtime, |
| | } |
| | return res |
| |
|
| | def created(self, path): |
| | """Return the created timestamp of a file as a datetime.datetime""" |
| | wpath = _as_unc_path(self.host, path) |
| | stats = smbclient.stat(wpath, port=self._port) |
| | return datetime.datetime.fromtimestamp(stats.st_ctime, tz=datetime.timezone.utc) |
| |
|
| | def modified(self, path): |
| | """Return the modified timestamp of a file as a datetime.datetime""" |
| | wpath = _as_unc_path(self.host, path) |
| | stats = smbclient.stat(wpath, port=self._port) |
| | return datetime.datetime.fromtimestamp(stats.st_mtime, tz=datetime.timezone.utc) |
| |
|
| | def ls(self, path, detail=True, **kwargs): |
| | unc = _as_unc_path(self.host, path) |
| | listed = smbclient.listdir(unc, port=self._port, **kwargs) |
| | dirs = ["/".join([path.rstrip("/"), p]) for p in listed] |
| | if detail: |
| | dirs = [self.info(d) for d in dirs] |
| | return dirs |
| |
|
| | |
| | def _open( |
| | self, |
| | path, |
| | mode="rb", |
| | block_size=-1, |
| | autocommit=True, |
| | cache_options=None, |
| | **kwargs, |
| | ): |
| | """ |
| | block_size: int or None |
| | If 0, no buffering, 1, line buffering, >1, buffer that many bytes |
| | |
| | Notes |
| | ----- |
| | By specifying 'share_access' in 'kwargs' it is possible to override the |
| | default shared access setting applied in the constructor of this object. |
| | """ |
| | bls = block_size if block_size is not None and block_size >= 0 else -1 |
| | wpath = _as_unc_path(self.host, path) |
| | share_access = kwargs.pop("share_access", self.share_access) |
| | if "w" in mode and autocommit is False: |
| | temp = _as_temp_path(self.host, path, self.temppath) |
| | return SMBFileOpener( |
| | wpath, temp, mode, port=self._port, block_size=bls, **kwargs |
| | ) |
| | return smbclient.open_file( |
| | wpath, |
| | mode, |
| | buffering=bls, |
| | share_access=share_access, |
| | port=self._port, |
| | **kwargs, |
| | ) |
| |
|
| | def copy(self, path1, path2, **kwargs): |
| | """Copy within two locations in the same filesystem""" |
| | wpath1 = _as_unc_path(self.host, path1) |
| | wpath2 = _as_unc_path(self.host, path2) |
| | smbclient.copyfile(wpath1, wpath2, port=self._port, **kwargs) |
| |
|
| | def _rm(self, path): |
| | if _share_has_path(path): |
| | wpath = _as_unc_path(self.host, path) |
| | stats = smbclient.stat(wpath, port=self._port) |
| | if S_ISDIR(stats.st_mode): |
| | smbclient.rmdir(wpath, port=self._port) |
| | else: |
| | smbclient.remove(wpath, port=self._port) |
| |
|
| | def mv(self, path1, path2, recursive=None, maxdepth=None, **kwargs): |
| | wpath1 = _as_unc_path(self.host, path1) |
| | wpath2 = _as_unc_path(self.host, path2) |
| | smbclient.rename(wpath1, wpath2, port=self._port, **kwargs) |
| |
|
| |
|
| | def _as_unc_path(host, path): |
| | rpath = path.replace("/", "\\") |
| | unc = f"\\\\{host}{rpath}" |
| | return unc |
| |
|
| |
|
| | def _as_temp_path(host, path, temppath): |
| | share = path.split("/")[1] |
| | temp_file = f"/{share}{temppath}/{uuid.uuid4()}" |
| | unc = _as_unc_path(host, temp_file) |
| | return unc |
| |
|
| |
|
| | def _share_has_path(path): |
| | parts = path.count("/") |
| | if path.endswith("/"): |
| | return parts > 2 |
| | return parts > 1 |
| |
|
| |
|
| | class SMBFileOpener: |
| | """writes to remote temporary file, move on commit""" |
| |
|
| | def __init__(self, path, temp, mode, port=445, block_size=-1, **kwargs): |
| | self.path = path |
| | self.temp = temp |
| | self.mode = mode |
| | self.block_size = block_size |
| | self.kwargs = kwargs |
| | self.smbfile = None |
| | self._incontext = False |
| | self.port = port |
| | self._open() |
| |
|
| | def _open(self): |
| | if self.smbfile is None or self.smbfile.closed: |
| | self.smbfile = smbclient.open_file( |
| | self.temp, |
| | self.mode, |
| | port=self.port, |
| | buffering=self.block_size, |
| | **self.kwargs, |
| | ) |
| |
|
| | def commit(self): |
| | """Move temp file to definitive on success.""" |
| | |
| | smbclient.replace(self.temp, self.path, port=self.port) |
| |
|
| | def discard(self): |
| | """Remove the temp file on failure.""" |
| | smbclient.remove(self.temp, port=self.port) |
| |
|
| | def __fspath__(self): |
| | return self.path |
| |
|
| | def __iter__(self): |
| | return self.smbfile.__iter__() |
| |
|
| | def __getattr__(self, item): |
| | return getattr(self.smbfile, item) |
| |
|
| | def __enter__(self): |
| | self._incontext = True |
| | return self.smbfile.__enter__() |
| |
|
| | def __exit__(self, exc_type, exc_value, traceback): |
| | self._incontext = False |
| | self.smbfile.__exit__(exc_type, exc_value, traceback) |
| |
|
