Estructura inicial funcional con documentación en el README.md de la FastAPI

This commit is contained in:
2026-09-25 11:20:50 -03:00
parent edc71742fa
commit 774e227642
2710 changed files with 1012769 additions and 0 deletions

View File

@@ -0,0 +1,47 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import smbclient.path
from smbclient._io import SEEK_CUR, SEEK_END, SEEK_SET
from smbclient._os import (
XATTR_CREATE,
XATTR_REPLACE,
SMBDirEntry,
SMBDirEntryInformation,
SMBScandirIterator,
SMBStatResult,
SMBStatVolumeResult,
copyfile,
getxattr,
link,
listdir,
liststreams,
listxattr,
lstat,
makedirs,
mkdir,
open_file,
readlink,
remove,
removedirs,
removexattr,
rename,
renames,
replace,
rmdir,
scandir,
setxattr,
stat,
stat_volume,
symlink,
truncate,
unlink,
utime,
walk,
)
from smbclient._pool import (
ClientConfig,
delete_session,
register_session,
reset_connection_cache,
)

View File

@@ -0,0 +1,702 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import io
import logging
import warnings
from smbclient._pool import ClientConfig, dfs_request, get_smb_tree
from smbprotocol import MAX_PAYLOAD_SIZE
from smbprotocol.exceptions import (
NoMoreFiles,
NoSuchFile,
ObjectNameNotFound,
ObjectPathNotFound,
PathNotCovered,
PipeBroken,
SMBOSError,
SMBResponseException,
)
from smbprotocol.file_info import FileAttributes, FileEndOfFileInformation
from smbprotocol.ioctl import IOCTLFlags, SMB2IOCTLRequest, SMB2IOCTLResponse
from smbprotocol.open import (
CreateDisposition,
CreateOptions,
FilePipePrinterAccessMask,
ImpersonationLevel,
Open,
QueryDirectoryFlags,
ShareAccess,
SMB2CreateRequest,
SMB2QueryInfoRequest,
SMB2QueryInfoResponse,
SMB2SetInfoRequest,
SMB2SetInfoResponse,
)
log = logging.getLogger(__name__)
SEEK_SET = io.SEEK_SET
SEEK_CUR = io.SEEK_CUR
SEEK_END = io.SEEK_END
def _parse_share_access(raw, mode):
share_access = 0
if raw:
share_access_map = {
"r": ShareAccess.FILE_SHARE_READ,
"w": ShareAccess.FILE_SHARE_WRITE,
"d": ShareAccess.FILE_SHARE_DELETE,
}
for c in raw:
access_val = share_access_map.get(c)
if access_val is None:
chars = ", ".join(sorted(share_access_map.keys()))
raise ValueError(f"Invalid share_access char {c}, can only be {chars}")
share_access |= access_val
if "r" in mode:
share_access |= ShareAccess.FILE_SHARE_READ
return share_access
def _parse_mode(raw, invalid=""):
create_disposition = 0
disposition_map = {
"r": CreateDisposition.FILE_OPEN,
"w": CreateDisposition.FILE_OVERWRITE_IF,
"x": CreateDisposition.FILE_CREATE,
"a": CreateDisposition.FILE_OPEN_IF,
# These have no bearing on the CreateDisposition but are here so ValueError isn't raised
"+": 0,
"b": 0,
"t": 0,
}
if invalid:
for invalid_char in invalid:
del disposition_map[invalid_char]
for c in raw:
dispo_val = disposition_map.get(c)
if dispo_val is None:
chars = ", ".join(sorted(disposition_map.keys()))
raise ValueError(
f"Invalid mode char {c}, can only be {chars}",
)
create_disposition |= dispo_val
if create_disposition == 0:
raise ValueError(f"Invalid mode value {raw}, must contain at least r, w, x, or a")
return create_disposition
def _chunk_size(connection, length, operation):
"""
Get the maximum size of data we can read/write. Also gets the number of credits to request to optimize subsequent
read/write operations for the remaining length.
:param connection: The SMB connection.
:param length: The length of the data we are working with.
:param operation: The operation the chunk is for: 'read', 'write', 'transact'
:return: The size of the chunk we can use and the number of credits to request for the next operation.
"""
max_size = getattr(connection, f"max_{operation}_size")
# Determine the maximum data length we can send for the operation. We do this by checking the available credits and
# calculating whatever is the smallest; length, negotiated operation size, available credit size).
available_credits = connection.sequence_window["high"] - connection.sequence_window["low"]
chunk_size = min(length, max_size, available_credits * MAX_PAYLOAD_SIZE)
# Determine how many credits we need to fully optimize subsequent calls for the remaining amount of data. Basically
# how many credits we need to send either the remaining data or the max operation size.
remaining_length = min(max(0, length - chunk_size), max_size)
consumed_credits = (max(0, chunk_size - 1) // MAX_PAYLOAD_SIZE) + 1
remaining_credits = (max(0, remaining_length - 1) // MAX_PAYLOAD_SIZE) + 1
desired_credits = max(0, remaining_credits - available_credits - consumed_credits)
credit_request = consumed_credits + desired_credits
return chunk_size, int(credit_request)
def _resolve_dfs(raw_io):
"""
Resolves a DFS path for a failed Open request.
:param raw_io: The SMBRawIO to resolve the DFS path for.
:return: A new Open for each DFS target that was resolved.
"""
if not raw_io.fd.tree_connect.is_dfs_share:
return
# Path is on a DFS root that is linked to another server.
client_config = ClientConfig()
raw_path = raw_io.name
referral = dfs_request(raw_io.fd.tree_connect, raw_path[1:])
client_config.cache_referral(referral)
info = client_config.lookup_referral([p for p in raw_path.split("\\") if p])
if not info:
raise ObjectPathNotFound()
connection_kwargs = getattr(raw_io, f"_{SMBRawIO.__name__}__kwargs", {})
for target in info:
new_path = raw_path.replace(info.dfs_path, target.target_path, 1)
try:
tree, fd_path = get_smb_tree(new_path, **connection_kwargs)
except SMBResponseException as link_exc:
log.warning("Failed to connect to DFS link target %s", target, exc_info=link_exc)
continue
# Record the target that worked for future reference.
info.target_hint = target
yield Open(tree, fd_path)
def _next_dfs_referral(raw_io, attempted_paths):
"""
Walk DFS referrals for ``raw_io`` and return the next candidate ``Open`` whose
(share_name, file_name) hasn't been attempted yet. Returns ``None`` if all
referrals are exhausted, letting the caller re-raise the original DFS error.
Used by both :class:`SMBFileTransaction` (open/CreateRequest path) and
:meth:`SMBDirectoryIO.query_directory` (already-open enumeration path) so
they share a single source of truth for DFS retry selection. Each caller
is still responsible for swapping the underlying fd after a candidate is
returned because that step differs (transaction mutates ``_actions`` while
the directory IO closes/reopens the fd).
:param raw_io: The SMBRawIO whose path returned STATUS_PATH_NOT_COVERED or
a generic name/path-not-found that's actually DFS.
:param attempted_paths: Mutable set used to dedupe referral targets across
multiple retries within a single operation. See
https://github.com/jborean93/smbprotocol/issues/228.
:return: A new ``Open`` instance for the caller to use, or ``None``.
"""
for smb_open in _resolve_dfs(raw_io):
if smb_open.tree_connect.share_name == raw_io.fd.tree_connect.share_name:
continue
tested_path = f"{smb_open.tree_connect.share_name}{smb_open.file_name}".lower()
if tested_path in attempted_paths:
continue
attempted_paths.add(tested_path)
return smb_open
return None
def ioctl_request(transaction, ctl_code, output_size=0, flags=IOCTLFlags.SMB2_0_IOCTL_IS_IOCTL, input_buffer=b""):
"""
Sends an IOCTL request to the server.
:param transaction: The SMBFileTransaction the request is to run under.
:param ctl_code: The IOCTL Code of the request.
:param output_size: Specify the max output response allowed from the server.
:param flags: Specify custom flags to be set on the IOCTL request.
:param input_buffer: Specify an optional input buffer for the request.
"""
ioctl_req = SMB2IOCTLRequest()
ioctl_req["ctl_code"] = ctl_code
ioctl_req["file_id"] = transaction.raw.fd.file_id
ioctl_req["max_output_response"] = output_size
ioctl_req["flags"] = flags
ioctl_req["buffer"] = input_buffer
def _receive_resp(request):
response = transaction.raw.fd.connection.receive(request)
query_resp = SMB2IOCTLResponse()
query_resp.unpack(response["data"].get_value())
return query_resp["buffer"].get_value()
transaction += (ioctl_req, _receive_resp)
def query_info(transaction, info_class, flags=0, output_buffer_length=None):
"""
Sends a QUERY INFO request to the server for the information class passed in.
:param transaction: The SMBFileTransaction the request is to run under.
:param info_class: The required information class type defined in file_info.py that is being requested.
:param flags: Optional flags to set on the query request.
:param output_buffer_length: Override the max output buffer length, defaults to the size of the information class.
"""
info_obj = info_class()
query_req = SMB2QueryInfoRequest()
query_req["info_type"] = info_obj.INFO_TYPE
query_req["file_info_class"] = info_obj.INFO_CLASS
query_req["file_id"] = transaction.raw.fd.file_id
query_req["output_buffer_length"] = len(info_obj) if output_buffer_length is None else output_buffer_length
query_req["flags"] = flags
def _receive_resp(request):
response = transaction.raw.fd.connection.receive(request)
query_resp = SMB2QueryInfoResponse()
query_resp.unpack(response["data"].get_value())
return query_resp.parse_buffer(info_class)
transaction += (query_req, _receive_resp)
def set_info(transaction, info_buffer):
"""
Sends a SET INFO request to the server with the information class input.
:param transaction: The SMBFileTransaction the request is to run under.
:param info_buffer: The input information class to set.
"""
set_req = SMB2SetInfoRequest()
set_req["info_type"] = info_buffer.INFO_TYPE
set_req["file_info_class"] = info_buffer.INFO_CLASS
set_req["file_id"] = transaction.raw.fd.file_id
set_req["buffer"] = info_buffer
def _receive_resp(request):
response = transaction.raw.fd.connection.receive(request)
set_resp = SMB2SetInfoResponse()
set_resp.unpack(response["data"].get_value())
return set_resp
transaction += (set_req, _receive_resp)
class SMBFileTransaction:
def __init__(self, raw):
"""
Stores compound requests in 1 class that can be committed when required. Either uses the opened raw object or
if that is not opened, opens and closes it in the 1 request.
:param raw: The SMBRawIO object to run the compound request with.
"""
self.raw = raw
self.results = None
self._actions = []
self._attempted_dfs_paths = set()
def __add__(self, other):
send_msg = other[0]
unpack_func = other[1]
self._actions.append((send_msg, unpack_func))
return self
def __enter__(self):
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.commit()
def commit(self):
"""
Sends a compound request to the server. Optionally opens and closes a handle in the same request if the handle
is not already opened.
"""
remove_index = []
if self.raw.closed and (not self._actions or not isinstance(self._actions[0][0], SMB2CreateRequest)):
self.raw.open(transaction=self)
self._actions.insert(0, self._actions.pop(-1)) # Need to move the create to the start
remove_index.insert(0, 0)
self.raw.close(transaction=self)
remove_index.insert(0, len(self._actions) - 1)
send_msgs = []
unpack_functions = []
for action in self._actions:
send_msgs.append(action[0])
unpack_functions.append(action[1])
sid = self.raw.fd.tree_connect.session.session_id
tid = self.raw.fd.tree_connect.tree_connect_id
requests = self.raw.fd.connection.send_compound(send_msgs, sid, tid, related=True)
# Due to a wonderful threading issue we need to ensure we call .receive() for each message we sent so cannot
# just enumerate the list in 1 line in case it throws an exception.
failures = []
responses = []
try_again = False
for idx, func in enumerate(unpack_functions):
res = None
try:
try:
res = func(requests[idx])
except (PathNotCovered, ObjectNameNotFound, ObjectPathNotFound):
# The MS-DFSC docs state that STATUS_PATH_NOT_COVERED is used when encountering a link to a
# different server but Samba seems to return the generic name or path not found.
# If the first action is not a CreateRequest then we can't resolve the DFS path in the transaction.
if not (idx == 0 and isinstance(send_msgs[0], SMB2CreateRequest)):
raise
smb_open = _next_dfs_referral(self.raw, self._attempted_dfs_paths)
if smb_open is None:
# No DFS referrals or all of them already attempted; propagate the error.
raise
self.raw.fd = smb_open
# In case this is a transaction with an explicit open we want to reopen it with the new params
# before trying it again.
self.raw.open(transaction=self)
self._actions[0] = self._actions.pop(-1)
try_again = True
except SMBResponseException as exc:
failures.append(SMBOSError(exc.status, self.raw.name))
finally:
responses.append(res)
# Remove the existing open/close actions this transaction added internally.
for idx in remove_index:
del self._actions[idx]
del responses[idx]
if try_again:
# If we updated the SMB Tree due to a DFS referral hit then try again.
self.commit()
elif failures:
# If there was a failure, just raise the first exception found.
raise failures[0]
else:
self.results = tuple(responses)
class SMBRawIO(io.RawIOBase):
FILE_TYPE = None # 'file', 'dir', or None (for unknown)
_INVALID_MODE = ""
def __init__(
self, path, mode="r", share_access=None, desired_access=None, file_attributes=None, create_options=0, **kwargs
):
# get_smb_tree runs outside the SMBFileTransaction layer that normally translates these.
try:
tree, fd_path = get_smb_tree(path, **kwargs)
except SMBResponseException as exc:
raise SMBOSError(exc.status, path) from exc
self.share_access = share_access
self.fd = Open(tree, fd_path)
self._mode = mode
self._name = path
self._offset = 0
self._flush = False
self.__kwargs = kwargs # Used in open for DFS referrals
if desired_access is None:
desired_access = 0
# While we can open a directory, the values for FilePipePrinterAccessMask also apply to Dirs so just use
# the same enum to simplify code.
if "r" in self.mode or "+" in self.mode:
desired_access |= (
FilePipePrinterAccessMask.FILE_READ_DATA
| FilePipePrinterAccessMask.FILE_READ_ATTRIBUTES
| FilePipePrinterAccessMask.FILE_READ_EA
)
if "w" in self.mode or "x" in self.mode or "a" in self.mode or "+" in self.mode:
desired_access |= (
FilePipePrinterAccessMask.FILE_WRITE_DATA
| FilePipePrinterAccessMask.FILE_WRITE_ATTRIBUTES
| FilePipePrinterAccessMask.FILE_WRITE_EA
)
self._desired_access = desired_access
if file_attributes is None:
file_attributes = (
FileAttributes.FILE_ATTRIBUTE_DIRECTORY
if self.FILE_TYPE == "dir"
else FileAttributes.FILE_ATTRIBUTE_NORMAL
)
self._file_attributes = file_attributes
self._create_options = create_options
self._create_options |= {
"dir": CreateOptions.FILE_DIRECTORY_FILE,
"file": CreateOptions.FILE_NON_DIRECTORY_FILE,
}.get(self.FILE_TYPE, 0)
super().__init__()
def __del__(self):
# io.IOBase.__del__ would call self.close(), which self-deadlocks if GC
# runs it on the SMB worker thread.
try:
closed = self.closed
except AttributeError:
return
if closed:
return
warnings.warn(f"unclosed SMB handle {self._name!r}", ResourceWarning, source=self)
def __enter__(self):
self.open()
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.close()
@property
def closed(self):
return not self.fd.connected
@property
def mode(self):
return self._mode
@property
def name(self):
return self._name
def close(self, transaction=None):
if transaction:
transaction += self.fd.close(send=False)
else:
self.fd.close()
def flush(self):
if self._flush and self.FILE_TYPE != "pipe":
self.fd.flush()
def open(self, transaction=None):
if not self.closed:
return
open_at_end = False
if not transaction:
# The SMBFileTransaction has special logic that deals with DFS paths, use that to do the actual open.
open_at_end = True
transaction = SMBFileTransaction(self)
share_access = _parse_share_access(self.share_access, self.mode)
create_disposition = _parse_mode(self.mode, invalid=self._INVALID_MODE)
# https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-wpo/feeb3122-cfe0-4b34-821d-e31c036d763c
# Impersonation on SMB has little meaning when opening files but is important if using RPC so set to a sane
# default of Impersonation.
transaction += self.fd.create(
ImpersonationLevel.Impersonation,
self._desired_access,
self._file_attributes,
share_access,
create_disposition,
self._create_options,
send=False,
)
if open_at_end:
transaction.commit()
if "a" in self.mode and self.FILE_TYPE != "pipe":
self._offset = self.fd.end_of_file
def readable(self):
"""True if file was opened in a read mode."""
return "r" in self.mode or "+" in self.mode
def seek(self, offset, whence=SEEK_SET):
"""
Move to new file position and return the file position.
Argument offset is a byte count. Optional argument whence defaults to
SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values
are SEEK_CUR or 1 (move relative to current position, positive or negative),
and SEEK_END or 2 (move relative to end of file, usually negative, although
many platforms allow seeking beyond the end of a file).
Note that not all file objects are seekable.
"""
seek_offset = {
SEEK_SET: 0,
SEEK_CUR: self._offset,
SEEK_END: self.fd.end_of_file,
}[whence]
self._offset = seek_offset + offset
return self._offset
def seekable(self):
"""True if file supports random-access."""
return True
def tell(self):
"""
Current file position.
Can raise OSError for non seekable files.
"""
return self._offset
def truncate(self, size):
"""
Truncate the file to at most size bytes and return the truncated size.
Size defaults to the current file position, as returned by tell().
The current file position is changed to the value of size.
"""
with SMBFileTransaction(self) as transaction:
eof_info = FileEndOfFileInformation()
eof_info["end_of_file"] = size
set_info(transaction, eof_info)
self.fd.end_of_file = size
self._flush = True
return size
def writable(self):
"""True if file was opened in a write mode."""
return "w" in self.mode or "x" in self.mode or "a" in self.mode or "+" in self.mode
def readall(self):
"""
Read and return all the bytes from the stream until EOF, using
multiple calls to the stream if necessary.
:return: The byte string read from the SMB file.
"""
data = bytearray()
while True:
read_length = min(
# We always want to be reading a minimum of 64KiB.
max(self.fd.end_of_file - self._offset, MAX_PAYLOAD_SIZE),
self.fd.connection.max_read_size, # We can never read more than this.
)
buffer = bytearray(b"\x00" * read_length)
bytes_read = self.readinto(buffer)
if not bytes_read:
break
data += buffer[:bytes_read]
return bytes(data)
def readinto(self, b):
"""
Read bytes into a pre-allocated, writable bytes-like object b, and
return the number of bytes read. This may read less bytes than
requested as it depends on the negotiated read size and SMB credits
available.
:param b: bytes-like object to read the data into.
:return: The number of bytes read.
"""
if self._offset >= self.fd.end_of_file and self.FILE_TYPE != "pipe":
return 0
chunk_size, credit_request = _chunk_size(self.fd.connection, len(b), "read")
log.debug("Read %d -%d.", self._offset, chunk_size)
read_msg, recv_func = self.fd.read(self._offset, chunk_size, send=False)
request = self.fd.connection.send(
read_msg,
sid=self.fd.tree_connect.session.session_id,
tid=self.fd.tree_connect.tree_connect_id,
credit_request=credit_request,
)
try:
file_bytes = recv_func(request)
except PipeBroken:
# A pipe will block until it returns the data available or was closed/broken.
file_bytes = b""
b[: len(file_bytes)] = file_bytes
if self.FILE_TYPE != "pipe":
self._offset += len(file_bytes)
return len(file_bytes)
def write(self, b):
"""
Write buffer b to file, return number of bytes written.
Only makes one system call, so not all of the data may be written.
The number of bytes actually written is returned. This can be less than
the length of b as it depends on the underlying connection.
"""
chunk_size, credit_request = _chunk_size(self.fd.connection, len(b), "write")
data = bytes(b[:chunk_size])
write_msg, recv_func = self.fd.write(data, offset=self._offset, send=False)
request = self.fd.connection.send(
write_msg,
sid=self.fd.tree_connect.session.session_id,
tid=self.fd.tree_connect.tree_connect_id,
credit_request=credit_request,
)
bytes_written = recv_func(request)
if self.FILE_TYPE != "pipe":
self._offset += bytes_written
self.fd.end_of_file = max(self.fd.end_of_file, self._offset)
self._flush = True
return bytes_written
class SMBDirectoryIO(SMBRawIO):
FILE_TYPE = "dir"
_INVALID_MODE = "w+"
def query_directory(self, pattern, info_class):
query_flags = QueryDirectoryFlags.SMB2_RESTART_SCANS
attempted_dfs_paths = set()
while True:
try:
entries = self.fd.query_directory(pattern, info_class, flags=query_flags)
except (NoMoreFiles, NoSuchFile):
# MS-SMB2 3.3.5.18 lists both as QUERY_DIRECTORY end codes. A server
# returns STATUS_NO_SUCH_FILE when the search pattern matches no files.
# Treat either as end of enumeration.
break
except (PathNotCovered, ObjectNameNotFound, ObjectPathNotFound):
# The MS-DFSC docs state that STATUS_PATH_NOT_COVERED is used when encountering a DFS link to a
# different server during directory enumeration. Samba may return the generic name or path not found.
smb_open = _next_dfs_referral(self, attempted_dfs_paths)
if smb_open is None:
# No DFS referral resolved; propagate the error.
raise
try:
self.fd.close()
except SMBResponseException:
pass
self.fd = smb_open
self.open()
query_flags = QueryDirectoryFlags.SMB2_RESTART_SCANS
continue
query_flags = 0 # Only the first request should have set SMB2_RESTART_SCANS
yield from entries
def readable(self):
return False
def seekable(self):
return False
def writable(self):
return False
class SMBFileIO(SMBRawIO):
FILE_TYPE = "file"
class SMBPipeIO(SMBRawIO):
FILE_TYPE = "pipe"
def seekable(self):
return False

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,466 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
from __future__ import annotations
import atexit
import logging
import ntpath
import uuid
from typing import Literal, Optional
from smbprotocol._text import to_text
from smbprotocol.connection import Capabilities, Connection
from smbprotocol.dfs import (
DFSReferralEntryFlags,
DFSReferralRequest,
DFSReferralResponse,
DomainEntry,
ReferralEntry,
)
from smbprotocol.exceptions import (
BadNetworkName,
FSDriverRequired,
InvalidParameter,
ObjectPathNotFound,
)
from smbprotocol.ioctl import CtlCode, IOCTLFlags, SMB2IOCTLRequest, SMB2IOCTLResponse
from smbprotocol.session import Session
from smbprotocol.tree import TreeConnect
log = logging.getLogger(__name__)
_SMB_CONNECTIONS = {}
class _ConfigSingleton(type):
__instances = {}
def __call__(cls, *args, **kwargs):
if cls not in cls.__instances:
config = super().__call__(*args, **kwargs)
cls.__instances[cls] = config
# Needs to be done after the config instance is in the singleton dict due to setting this value will kick
# off an IPC connection which then gets and instance of this config to see what the default creds are.
# The property will not run the DFS request if the passed in value matches what is already there. Set
# to None initially to ensure it detects a changed value.
# https://github.com/jborean93/smbprotocol/issues/109
dc_value = config.domain_controller
config.domain_controller = None
config.domain_controller = dc_value
else:
# Allow users to initialise and set multiple config options like ConfigType(key=value) even when the object
# has been initialized already.
config = cls.__instances[cls]
config.set(**kwargs)
return config
class ClientConfig(metaclass=_ConfigSingleton):
"""SMB Client global settings
This class defines global settings for the client that affects all connections that the client makes. When setting
the `domain_controller` config option, a DFS domain referral request is send to that hostname. It will use the
credentials provided in the config if set.
Attributes:
client_guid (uuid.UUID): The client GUID used when creating a connection to the server.
username (Optional[str]): Optional default username used when creating a new SMB session.
password (Optional[str]): Optional default password used when creating a new SMB session.
domain_controller (Optional[str]): The domain controller hostname. When set the config will send a DFS referral
request to this hostname to populate the domain cache used for DFS connections or when connecting to
`SYSVOL` or `NETLOGON`
skip_dfs (bool): Whether to skip using any DFS referral checks and treat any path as a normal path. This is
only useful if there are problems with the DFS resolver or you wish to avoid the extra round trip(s) the
resolver requires.
auth_protocol (str): The protocol to use for authentication. Possible values are 'negotiate', 'ntlm' or
'kerberos'. Defaults to 'negotiate'.
require_secure_negotiate (bool): Whether to verify the negotiated dialects and capabilities on the connection
to a share to protect against MitM downgrade attacks..
"""
def __init__(
self,
client_guid=None,
username=None,
password=None,
domain_controller=None,
skip_dfs=False,
auth_protocol="negotiate",
require_secure_negotiate=True,
**kwargs,
):
self.client_guid = client_guid or uuid.uuid4()
self.username = username
self.password = password
self.skip_dfs = skip_dfs
self.auth_protocol = auth_protocol
self.require_secure_negotiate = require_secure_negotiate
self._domain_controller: str | None = domain_controller
self._domain_cache: list[DomainEntry] = []
self._referral_cache: list[ReferralEntry] = []
@property
def domain_controller(self):
return self._domain_controller
@domain_controller.setter
def domain_controller(self, value):
"""Setting the domain controller will try to get any DFS domain referrals for future lookups."""
if self._domain_controller == value:
return
self._domain_controller = value
self._domain_cache = []
if not value or self.skip_dfs:
return
ipc_tree = get_smb_tree(rf"\\{value}\IPC$")[0]
try:
domain_referral_response = dfs_request(ipc_tree, "")
except InvalidParameter:
log.warning(
"Specified domain controller %s return STATUS_INVALID_PARAMETER, cannot use as DFS domain "
"cache source",
value,
)
return
for domain_referral in domain_referral_response["referral_entries"].get_value():
if not domain_referral["referral_entry_flags"].has_flag(DFSReferralEntryFlags.NAME_LIST_REFERRAL):
continue
self._domain_cache.append(DomainEntry(domain_referral))
def cache_referral(self, referral):
if referral["number_of_referrals"].get_value() > 0:
self._referral_cache.append(ReferralEntry(referral))
def lookup_domain(self, domain_name: str) -> DomainEntry | None:
# TODO: Check domain referral expiry and resend request if expired
for domain in self._domain_cache:
if domain.domain_name.lower() == ("\\" + domain_name.lower()):
return domain
def lookup_referral(self, path_components: list[str]) -> ReferralEntry | None:
"""Checks if the path exists in the DFS referral cache."""
# A lookup in ReferralCache involves searching for an entry with DFSPathPrefix that is a complete prefix of the
# path being looked up.
self._clear_expired_cache()
hits = []
for referral in self._referral_cache:
referral_path_components = [p for p in referral.dfs_path.split("\\") if p]
for idx, referral_component in enumerate(referral_path_components):
if idx >= len(path_components) or referral_component != path_components[idx]:
break
else:
hits.append(referral)
if hits:
# In the event of multiple matches, the longest match is used.
hits.sort(key=lambda h: len(h.dfs_path), reverse=True)
return hits[0]
def set(self, **config):
domain_controller = False
for key, value in config.items():
if key.startswith("_"):
raise ValueError(f"Cannot set private attribute {key}")
elif key == "domain_controller":
# This must be set last in case we are setting any username/password used for a domain referral lookup.
domain_controller = True
else:
setattr(self, key, value)
# Make sure we set this last in case different credentials were specified in the config
if domain_controller:
self.domain_controller = config["domain_controller"]
def _clear_expired_cache(self) -> None:
self._referral_cache = [refferal for refferal in self._referral_cache if not refferal.is_expired]
def dfs_request(tree: TreeConnect, path: str) -> DFSReferralResponse:
"""Send a DFS Referral request to the IPC tree and return the referrals."""
dfs_referral = DFSReferralRequest()
dfs_referral["request_file_name"] = to_text(path)
ioctl_req = SMB2IOCTLRequest()
ioctl_req["ctl_code"] = CtlCode.FSCTL_DFS_GET_REFERRALS
ioctl_req["file_id"] = b"\xff" * 16
ioctl_req["max_output_response"] = 56 * 1024
ioctl_req["flags"] = IOCTLFlags.SMB2_0_IOCTL_IS_FSCTL
ioctl_req["buffer"] = dfs_referral
request = tree.session.connection.send(ioctl_req, sid=tree.session.session_id, tid=tree.tree_connect_id)
response = tree.session.connection.receive(request)
ioctl_resp = SMB2IOCTLResponse()
ioctl_resp.unpack(response["data"].get_value())
dfs_response = DFSReferralResponse()
dfs_response.unpack(ioctl_resp["buffer"].get_value())
return dfs_response
def delete_session(server, port=445, connection_cache=None, timeout=60):
"""
Deletes the connection in the connection pool for the server specified. This will also close all sessions
associated with the connection.
:param server: The server name to close/delete.
:param port: The port used for the server.
:param connection_cache: Connection cache to be used with
"""
connection_key = f"{server.lower()}:{port}"
if connection_cache is None:
connection_cache = _SMB_CONNECTIONS
connection = connection_cache.get(connection_key, None)
if connection:
del connection_cache[connection_key]
connection.disconnect(close=True, timeout=timeout)
def get_smb_tree(
path,
username=None,
password=None,
port=445,
encrypt=None,
connection_timeout=60,
connection_cache=None,
auth_protocol=None,
require_signing=True,
):
"""
Returns an active Tree connection and file path including the tree based on the UNC path passed in and other
connection arguments. The opened connection is registered in a pool and re-used if a connection is made to the same
server with the same credentials.
:param path: The absolute UNC path we want to open a tree connect to.
:param username: Optional username to connect with. Required if no session has been registered for the server and
Kerberos auth is not being used.
:param password: Optional password to connect with.
:param port: The port to connect with.
:param encrypt: Whether to force encryption or not, once this has been set to True the session cannot be changed
back to False.
:param connection_timeout: Override the timeout used for the initial connection.
:param connection_cache: Connection cache to be used with
:return: The TreeConnect and file path including the tree based on the UNC path passed in.
"""
# Ensure our defaults use the value from the client set config.
client_config = ClientConfig()
username = username or client_config.username
password = password or client_config.password
auth_protocol = auth_protocol or client_config.auth_protocol
# In case we need to nest a call to get_smb_tree, preserve the kwargs here so it's easier to update them in case
# new kwargs are added.
get_kwargs = {
"username": username,
"password": password,
"port": port,
"encrypt": encrypt,
"connection_timeout": connection_timeout,
"connection_cache": connection_cache,
"auth_protocol": auth_protocol,
"require_signing": require_signing,
}
# Normalise and check that the path contains at least 2 components, \\server\share
path = ntpath.normpath(path)
path_split = [p for p in path.split("\\") if p]
if len(path_split) < 2:
raise ValueError("The SMB path specified must contain the server and share to connect to")
# Check if we've already got a referral match for the path specified and use that path instead.
referral = client_config.lookup_referral(path_split)
if referral and not referral.is_expired:
path = path.replace(referral.dfs_path, referral.target_hint.target_path, 1)
path_split = [p for p in path.split("\\") if p]
else:
# If there was no referral match, check if the hostname portion matches any known domain names
domain_referral = client_config.lookup_domain(path_split[0])
if domain_referral and not domain_referral.is_valid:
# If the path is a valid domain name but our domain referral is not currently valid, issue a DC referral
# to our known domain controller.
ipc_tree = get_smb_tree(rf"\\{client_config.domain_controller}\IPC$", **get_kwargs)[0]
referral_response = dfs_request(ipc_tree, domain_referral.domain_name)
domain_referral.process_dc_referral(referral_response)
if domain_referral:
# Use the dc hint as the source for the root referral request
ipc_tree = get_smb_tree(rf"\{domain_referral.dc_hint}\IPC$", **get_kwargs)[0]
referral_response = dfs_request(ipc_tree, rf"\{path_split[0]}\{path_split[1]}")
client_config.cache_referral(referral_response)
referral = client_config.lookup_referral(path_split)
if not referral:
raise ObjectPathNotFound()
path = path.replace(referral.dfs_path, referral.target_hint.target_path, 1)
path_split = [p for p in path.split("\\") if p]
server = path_split[0]
session = register_session(
server,
username=username,
password=password,
port=port,
encrypt=encrypt,
connection_timeout=connection_timeout,
connection_cache=connection_cache,
auth_protocol=auth_protocol,
require_signing=require_signing,
)
share_path = rf"\\{server}\{path_split[1]}"
tree = next((t for t in session.tree_connect_table.values() if t.share_name == share_path), None)
if not tree:
tree = TreeConnect(session, share_path)
try:
tree.connect(require_secure_negotiate=client_config.require_secure_negotiate)
except BadNetworkName as err:
# If the server doesn't mention it supports DFS then don't try to
# resolve the DFS path.
if not session.connection.server_capabilities.has_flag(Capabilities.SMB2_GLOBAL_CAP_DFS):
raise
ipc_path = rf"\\{server}\IPC$"
if path == ipc_path: # In case we already tried connecting to IPC$ but that failed.
raise
# The share could be a DFS root, issue a root referral request to the hostname and cache the result.
ipc_tree = get_smb_tree(ipc_path, **get_kwargs)[0]
try:
referral = dfs_request(ipc_tree, rf"\{path_split[0]}\{path_split[1]}")
except FSDriverRequired:
# If the DFS Request fails with STATUS_FS_DRIVER_REQUIRED then
# the server doesn't support DFS requests and the original
# BadNetworkName error should be raised instead of this one.
# This provides better context as to why a failure occured, i.e.
# a bad share path was provided.
# https://github.com/jborean93/smbprotocol/issues/196
raise err
client_config.cache_referral(referral)
# Sometimes a DFS referral may return 0 referrals, this needs to be checked here to avoid repeats.
if not client_config.lookup_referral(path_split):
raise ObjectPathNotFound()
return get_smb_tree(path, **get_kwargs)
# When opening a file on a DFS tree the raw path used in the CREATE
# request is the the original DFS path as the server should normalise
# it and return STATUS_PATH_NOT_COVERED if it's served by a DFS target
# server.
# https://github.com/jborean93/smbprotocol/issues/170
# https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/448cb979-7321-4598-89df-e5c97135b566
file_path = ""
if tree.is_dfs_share:
file_path = "\\".join(path_split)
elif len(path_split) > 2:
file_path = "\\".join(path_split[2:])
return tree, file_path
def register_session(
server: str,
username: Optional[str] = None,
password: Optional[str] = None,
port=445,
encrypt: Optional[bool] = None,
connection_timeout=60,
connection_cache=None,
auth_protocol: Literal["negotiate", "ntlm", "kerberos"] = "negotiate",
require_signing=True,
):
"""
Creates an active connection and session to the server specified. This can be manually called to register the
credentials of a specific server instead of defining it on the first function connecting to the server. The opened
connection is registered in a pool and re-used if a connection is made to the same server with the same
credentials.
:param server: The server name to register.
:param username: Optional username to connect with. Required if no session has been registered for the server and
Kerberos auth is not being used.
:param password: Optional password to connect with.
:param port: The port to connect with. Defaults to 445.
:param encrypt: Whether to force encryption or not, once this has been set to True the session cannot be changed
back to False.
:param connection_timeout: Override the timeout used for the initial connection.
:param connection_cache: Connection cache to be used with
:param auth_protocol: The protocol to use for authentication. Possible values are 'negotiate', 'ntlm' or
'kerberos'. Defaults to 'negotiate'.
:param require_signing: Whether signing is required on SMB messages sent over this session. Defaults to True.
:return: The Session that was registered or already existed in the pool.
"""
connection_key = f"{server.lower()}:{port}"
if connection_cache is None:
connection_cache = _SMB_CONNECTIONS
connection = connection_cache.get(connection_key, None)
# Make sure we ignore any connections that may have had a closed connection
if not connection or not connection.transport.connected:
connection = Connection(ClientConfig().client_guid, server, port, require_signing=require_signing)
connection.connect(timeout=connection_timeout)
connection_cache[connection_key] = connection
# Find the first session in the connection session list that match the username specified, if not username then
# just use the first session found or fall back to creating a new one with implicit auth/kerberos.
session = next((s for s in connection.session_table.values() if username is None or s.username == username), None)
if not session:
session = Session(
connection,
username=username,
password=password,
require_encryption=(encrypt is True),
auth_protocol=auth_protocol,
)
session.connect()
elif encrypt is not None:
# We cannot go from encryption to no encryption on an existing session but we can do the opposite.
if session.encrypt_data and not encrypt:
raise ValueError("Cannot disable encryption on an already negotiated session.")
elif not session.encrypt_data and encrypt:
session.encrypt = True
return session
# Make sure we run the function to close all the sessions when we exit Python
def reset_connection_cache(fail_on_error=True, connection_cache=None):
"""
Closes all the connections/sessions that have been pooled in the SMB Client. This allows a user to reset their
client in case of an unknown problem or they just wish to reset all the connections. It is also run on exit of the
Python interpreter to ensure the SMB connections are closed.
"""
if connection_cache is None:
connection_cache = _SMB_CONNECTIONS
for name in list(connection_cache.keys()):
connection = connection_cache.pop(name)
try:
connection.disconnect()
except Exception as e:
if fail_on_error:
raise
else:
log.warning("Failed to close connection %s", name, exc_info=e)
atexit.register(reset_connection_cache, fail_on_error=False)

View File

@@ -0,0 +1,151 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import errno
import stat as py_stat
from smbclient._os import stat
from smbprotocol.exceptions import SMBLinkRedirectionError, SMBOSError
def exists(path, **kwargs):
"""
Return True if path refers to an existing path. Returns False for broken symbolic links or links pointing to
unreachable locations.
:param path: The path to check if it exists.
:param kwargs: Common arguments used to build the SMB Session.
:return: Bool as to whether the path exists or not.
"""
return _exists(path, False, True, **kwargs)
def lexists(path, **kwargs):
"""
Return True if path refers to an existing path. Returns True for broken symbolic links or links pointing to
unreachable locations.
:param path: The path to check if it exists.
:param kwargs: Common arguments used to build the SMB Session.
:return: Bool as to whether the path exists or not.
"""
return _exists(path, True, False, **kwargs)
def getatime(path, **kwargs):
"""
Return the time of last access of path. The return value is a floating point number giving the number of seconds
since the epoch (see the time module). Raise OSError if the file does not exist or is inaccessible.
:param path: The path to get the atime for.
:param kwargs: Common arguments used to build the SMB Session.
:return: float that represents the number of seconds since epoch for atime.
"""
return stat(path, **kwargs).st_atime
def getmtime(path, **kwargs):
"""
Return the time of last modification of path. The return value is a floating point number giving the number of
seconds since the epoch (see the time module). Raise OSError if the file does not exist or is inaccessible.
:param path: The path to get the mtime for.
:param kwargs: Common arguments used to build the SMB Session.
:return: float that represents the number of seconds since epoch for atime.
"""
return stat(path, **kwargs).st_mtime
def getctime(path, **kwargs):
"""
Return the system’s ctime which is the creation time for path. The return value is a number giving the number of
seconds since the epoch (see the time module). Raise OSError if the file does not exist or is inaccessible.
:param path: The path to get the ctime for.
:param kwargs: Common arguments used to build the SMB Session.
:return: float that represents the number of seconds since epoch for atime.
"""
return stat(path, **kwargs).st_ctime
def getsize(path, **kwargs):
"""
Return the size, in bytes, of path. Raise OSError if the file does not exist or is inaccessible.
:param path: The path to get the size for.
:param kwargs: Common arguments used to build the SMB Session.
:return: The byte size of the path.
"""
return stat(path, **kwargs).st_size
def isfile(path, **kwargs):
"""
Return True if path is an existing regular file. This follows symbolic links, so both islink() and isfile() can be
true for the same path.
:param path: The path to check.
:param kwargs: Common arguments used to build the SMB Session.
:return: True if the path is a file or points to a file.
"""
return _stat_ismode(path, py_stat.S_ISREG, True, **kwargs)
def isdir(path, **kwargs):
"""
Return True if path is an existing directory. This follows symbolic links, so both islink() and isdir() can be true
for the same path.
:param path: The path to check.
:param kwargs: Common arguments used to build the SMB Session.
:return: True if path is a dir or points to a dir.
"""
return _stat_ismode(path, py_stat.S_ISDIR, True, **kwargs)
def islink(path, **kwargs):
"""
Return True if path is a symbolic link.
:param path: The path to check
:param kwargs: Common arguments used to build the SMB Session.
:return: True if path is a symlink.
"""
return _stat_ismode(path, py_stat.S_ISLNK, False, **kwargs)
def samefile(path1, path2, **kwargs):
"""
Return True if both pathname arguments refer to the same file or directory. This is determined by the device number
and i-node number and raises an exception if an os.stat() call on either pathname fails.
:param path1: The first path to compare.
:param path2: The second path to compare.
:param kwargs: Common arguments used to build the SMB Session.
:return: Bool that indicates whether the 2 files are the same.
"""
stat1 = stat(path1, **kwargs)
stat2 = stat(path2, **kwargs)
return stat1.st_ino == stat2.st_ino and stat1.st_dev == stat2.st_dev
def _exists(path, symlink_default, follow_symlinks, **kwargs):
try:
stat(path, follow_symlinks=follow_symlinks, **kwargs)
return True
except OSError as err:
if err.errno == errno.ENOENT:
return False
raise
except SMBLinkRedirectionError:
# Link points to another server or local drive, return false
return symlink_default
def _stat_ismode(path, check, follow, **kwargs):
try:
return check(stat(path, follow_symlinks=follow, **kwargs).st_mode)
except SMBOSError as err:
if err.errno == errno.ENOENT:
return False
raise

View File

@@ -0,0 +1,529 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com> and other contributors
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import errno
import ntpath
import os
import os.path
import shutil
import stat
import sys
from smbclient._io import SMBFileTransaction, SMBRawIO, query_info, set_info
from smbclient._os import (
SMBDirEntry,
)
from smbclient._os import copyfile as smbclient_copyfile
from smbclient._os import (
is_remote_path,
makedirs,
open_file,
readlink,
remove,
rmdir,
scandir,
)
from smbclient._os import stat as smbclient_stat
from smbclient._os import (
symlink,
)
from smbclient.path import isdir, islink, samefile
from smbprotocol import MAX_PAYLOAD_SIZE
from smbprotocol.exceptions import SMBOSError
from smbprotocol.file_info import FileAttributes, FileBasicInformation
from smbprotocol.header import NtStatus
from smbprotocol.open import CreateOptions, FilePipePrinterAccessMask
from smbprotocol.structure import DateTimeField
def _basename(path):
"""
Return the base name of pathname path.
This is the second element of the pair returned by passing path to the function split().
Note that the result of this function is different from the Unix basename program;
where basename for '/foo/bar/' returns 'bar', the basename() function returns an empty string ('').
:param path: The path to take the base of.
:return: The basename of the path.
"""
if is_remote_path(path):
return ntpath.basename(path)
else:
return os.path.basename(path)
def _join_local_or_remote_path(path, *paths):
"""
Return the joined paths regardless of whether they are local or remote.
Currently, this only makes the decision based on the base path, and does not raise a ValueError if the additional
paths do not match.
:param path: The base path.
:param paths: The additional paths to append.
:return: Joined path.
"""
if is_remote_path(path):
return ntpath.join(path, *paths)
else:
return os.path.join(path, *paths)
def copy(src, dst, follow_symlinks=True, **kwargs):
"""
Copies the file src to the file or directory dst. If dst specified a directory, the file will be copied into dst
using the base filename from src. Returns the path to the newly created file.
If follow_symlinks is 'False', and src is a symbolic link, dst will be created as a symbolic link. If
follow_symlinks is 'True' and src is a symbolic link, dst will be a copy of the file src refers to.
copy() copies the file data and file's permission mode which on Windows is only the read-only flag. All other
bits are ignored on a copy. Other metadata like file's creation and modification times, are not preserved.
:param src: The path to the source file to copy, if not an absolute path then this is relative to the current
directory.
:param dst: The path to the destination to copy the file t.
:param follow_symlinks: Whether to copy the symlink target of source or the symlink itself.
:param kwargs: Common arguments used to build the SMB Session for any UNC paths.
:return The path to the destination filename.
"""
return _copy(src, dst, follow_symlinks, copymode, **kwargs)
def copy2(src, dst, follow_symlinks=True, **kwargs):
"""
Identical to copy() except that copy2() also attempts to preserve the file metadata.
copy2() uses copystat() to copy the file metadata. Please see copystat() for more information about how and what
metadata it copies to the dst file.
:param src: The path to the source file to copy, if not an absolute path then this is relative to the current
directory.
:param dst: The path to the destination to copy the file t.
:param follow_symlinks: Whether to copy the symlink target of source or the symlink itself.
:param kwargs: Common arguments used to build the SMB Session for any UNC paths.
:return The path to the destination filename.
"""
return _copy(src, dst, follow_symlinks, copystat, **kwargs)
def copyfile(src, dst, follow_symlinks=True, **kwargs):
"""
Copy the contents (no metadata) of the file names src to a file named dst and return dst in the most efficient way
possible. If the src and dst reside on the same UNC share then a more efficient remote side copy is used. If the
src and dst reside on the same local path then the proper shutil.copyfile() method is called, otherwise the content
is copied using copyfileobj() in chunks.
dst must be the complete target file name; look at copy() for a copy that accepts a target directory path. If src
dst specify the same file, ValueError is raised.
The destination location must be writable; otherwise, an OSError exception will be raised. If dst already exists,
it will be replaced. Special files such as character or block devices and pipes cannot be copied with this
function.
If follow_symlinks is 'False' and src is a symbolic link, a new symbolic link will be created instead of copying
the file src points to. This will fail if the symbolic link at src is a different root as dst.
:param src: The src filepath to copy.
:param dst: The destination filepath to copy to.
:param follow_symlinks: Whether to copy the symlink target of source or the symlink itself.
:param kwargs: Common arguments used to build the SMB Session for any UNC paths.
:return: The dst path.
"""
norm_src = ntpath.normpath(src)
if is_remote_path(norm_src):
src_root = ntpath.splitdrive(norm_src)[0]
islink_func = islink
readlink_func = readlink
symlink_func = symlink
src_open = open_file
src_kwargs = kwargs
# Open the soruce with read file sharing to allow copying
# files already opened.
# https://github.com/jborean93/smbprotocol/issues/258
src_open_kwargs = kwargs.copy()
src_open_kwargs["share_access"] = "r"
else:
src_root = None
islink_func = os.path.islink
readlink_func = os.readlink
symlink_func = os.symlink
src_open = open
src_kwargs = src_open_kwargs = {}
norm_dst = ntpath.normpath(dst)
if is_remote_path(norm_dst):
dst_root = ntpath.splitdrive(norm_dst)[0]
dst_open = open_file
dst_kwargs = kwargs
else:
dst_root = None
dst_open = open
dst_kwargs = {}
if not follow_symlinks and islink_func(src, **src_kwargs):
if src_root != dst_root:
raise ValueError("Cannot copy a symlink on different roots.")
symlink_func(readlink_func(src), dst, **src_kwargs)
return dst
if src_root is None and dst_root is None:
# The files are local and follow_symlinks is True, rely on the builtin copyfile mechanism.
shutil.copyfile(src, dst)
return dst
if src_root == dst_root:
# The files are located on the same share and follow_symlinks is True, rely on smbclient.copyfile for an
# efficient server side copy.
try:
is_same = samefile(src, dst, **kwargs)
except OSError as err:
if err.errno == errno.ENOENT:
is_same = False
else:
raise
if is_same:
raise shutil.Error(f"'{src}' and '{dst}' are the same file, cannot copy")
# Attempt server side copy, if it fails fall back to copying the file in chunks using copyfileobj
try:
smbclient_copyfile(src, dst, **kwargs)
return dst
except SMBOSError as err:
if err.ntstatus != NtStatus.STATUS_NOT_SUPPORTED:
raise
# Finally we are copying across different roots so we just chunk the data using copyfileobj
with src_open(src, mode="rb", **src_open_kwargs) as src_fd, dst_open(dst, mode="wb", **dst_kwargs) as dst_fd:
copyfileobj(src_fd, dst_fd, MAX_PAYLOAD_SIZE)
return dst
# Because smbclient's open_file returns a file object this should just work.
copyfileobj = shutil.copyfileobj
def copymode(src, dst, follow_symlinks=True, **kwargs):
"""
Copy the permission bits from src to dst. The file contents, owner, and group are unaffected. Due to the
limitations of Windows, this function only sets/unsets the dst's FILE_ATTRIBUTE_READ_ONLY flag based on what src's
attribute is set to.
If follow_symlinks is 'False', and both src and dst are symbolic links, copymode() will attempt to modify the mode
of dst itself (rather than the file it points to).
This function supports src and dst being either a local or UNC path. A relative path will be resolved based on the
current working directory.
:param src: The src file or directory to copy the read only flag from.
:param dst: The dst file or directory to copy the read only flag to.
:param follow_symlinks: Whether to copy the read only flag on the symlink or the target of the symlink.
:param kwargs: Common arguments used to build the SMB Session for any UNC paths.
"""
src_mode = stat.S_IMODE(_get_file_stat(src, follow_symlinks, **kwargs).st_mode)
norm_dst = ntpath.normpath(dst)
if is_remote_path(norm_dst):
read_only = not (src_mode & stat.S_IWRITE == stat.S_IWRITE and src_mode & stat.S_IREAD == stat.S_IREAD)
_set_file_basic_info(dst, follow_symlinks, read_only=read_only, **kwargs)
else:
os.chmod(dst, src_mode, follow_symlinks=follow_symlinks)
def copystat(src, dst, follow_symlinks=True, **kwargs):
"""
Copy the read only attribute, last access time, and last modification time from src to dst. The file contents,
owner, and group are unaffected.
If follow_symlinks is 'False' and src and dst both refer to symbolic links, copystat() will operate on the
symbolic links themselves rather than the files the symbolic links refer to.
:param src: The src file or directory to copy the read only flag from.
:param dst: The dst file or directory to copy the read only flag to.
:param follow_symlinks: Whether to copy the read only flag on the symlink or the target of the symlink.
:param kwargs: Common arguments used to build the SMB Session for any UNC paths.
"""
src_stat = _get_file_stat(src, follow_symlinks, **kwargs)
src_mode = stat.S_IMODE(src_stat.st_mode)
atime_ns = src_stat.st_atime_ns
mtime_ns = src_stat.st_mtime_ns
norm_dst = ntpath.normpath(dst)
if is_remote_path(norm_dst):
read_only = not (src_mode & stat.S_IWRITE == stat.S_IWRITE and src_mode & stat.S_IREAD == stat.S_IREAD)
_set_file_basic_info(dst, follow_symlinks, read_only=read_only, atime_ns=atime_ns, mtime_ns=mtime_ns, **kwargs)
else:
os.chmod(dst, src_mode, follow_symlinks=follow_symlinks)
os.utime(dst, ns=(atime_ns, mtime_ns), follow_symlinks=follow_symlinks)
def copytree(
src,
dst,
symlinks=False,
ignore=None,
copy_function=copy2,
ignore_dangling_symlinks=False,
dirs_exist_ok=False,
**kwargs,
):
"""
Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination
directory. dirs_exist_ok dictates whether to raise an exception in case dst or any missing parent directory
exists.
Permissions and times of directories are copied with copystat(), individual files are copied using copy2().
If symlinks is 'True', symbolic links in the source tree are represented as symbolic links in the new tree and the
metadata of the original links will be copied as far as the platform allow; if 'False' or omitted, the contents and
metadata of the linked files are copied to the new tree.
When symlinks is 'False', if the file pointed by the symlink doesn't exist, an exception will be added in the list
of errors raises in an 'Error' exception at the end of the copy process. You can set the optional
ignore_dangling_symlinks flag to 'True' if you want to silence this exception.
if ignore is given, it must be a callable that will receive as its arguments the directory being visited by
copytree(), and a list of its contents, as returned by smbclient.listdir(). Since copytee() is called recursively,
the ignore callable will be called once for each directory that is copied. The callable must return a sequence of
directory and file names relative to the current directory (i.e. a subset of the items in its second argument);
these names will then be ignored in the copy process.
If exception(s) occur, an shutil.Error is raised with a list of reasons.
If copy_function is given, it must be a callable that will be used to copy each file. It will be called with the
source path and the destination path as arguments. By default copy() is used, but any function that supports the
same signature (like copy()) can be used.
:param src: The source directory to copy.
:param dst: The destination directory to copy to.
:param symlinks: Whether to attempt to copy a symlink from the source tree to the dest tree, if False the symlink
target's contents are copied instead as a normal file/dir.
:param ignore: A callable in the form 'callable(src, names) -> ignored_named' that returns a list of file names to
ignore based on the list passed in.
:param copy_function: The copy function to use for copying files.
:param ignore_dangling_symlinks: Ignore any broken symlinks, otherwise an Error is raised.
:param dirs_exist_ok: Whether to fail if the dst directory exists or not.
:param kwargs: Common arguments used to build the SMB Session for any UNC paths.
:return: The dst path.
"""
if is_remote_path(src):
with scandir(src, **kwargs) as scandir_gen:
dir_entries = list(scandir_gen)
else:
dir_entries = list(os.scandir(src))
if is_remote_path(dst):
makedirs(dst, exist_ok=dirs_exist_ok, **kwargs)
else:
os.makedirs(dst, exist_ok=dirs_exist_ok)
ignored = []
if ignore is not None:
ignored = ignore(src, [e.name for e in dir_entries])
errors = []
for dir_entry in dir_entries:
if dir_entry.name in ignored:
continue
src_path = _join_local_or_remote_path(src, dir_entry.name)
dst_path = _join_local_or_remote_path(dst, dir_entry.name)
try:
if dir_entry.is_symlink():
if not isinstance(dir_entry, SMBDirEntry):
raise AssertionError("copytree doesn't yet support symlinks for local to remote operations")
link_target = readlink(src_path, **kwargs)
if symlinks:
symlink(link_target, dst_path, **kwargs)
copystat(src_path, dst_path, follow_symlinks=False)
continue
else:
# Manually override the dir_entry with a new one that is the link target and copy that below.
try:
dir_entry = SMBDirEntry.from_path(link_target, **kwargs)
except OSError as err:
if err.errno == errno.ENOENT and ignore_dangling_symlinks:
continue
raise
if dir_entry.is_dir():
copytree(
src_path,
dst_path,
symlinks,
ignore,
copy_function,
ignore_dangling_symlinks,
dirs_exist_ok,
**kwargs,
)
else:
copy_function(src_path, dst_path, **kwargs)
except shutil.Error as err:
# From a recursive call of copytree().
errors.extend(err.args[0])
except OSError as err:
# Main smbclient operations should raise an OSError exception (or one that inherits OSError).
errors.append((src_path, dst_path, str(err)))
except ValueError as err:
# If the path is not supported or we are trying to symlink outside of the share boundary.
errors.append((src_path, dst_path, str(err)))
try:
copystat(src, dst)
except OSError as err:
errors.append((src, dst, str(err)))
if errors:
raise shutil.Error(errors)
return dst
def rmtree(path, ignore_errors=False, onerror=None, **kwargs):
"""
Recursively delete a directory tree; path must point to a directory (but not a symbolic link to a directory).
If ignore_errors is 'True', errors resulting from failed removals will be ignored; otherwise such errors are
handled by calling a handler specified by onerror or, if that is omitted, they raise an exception.
if onerror is provided, it must be a callable that accepts three parameters: function, path, excinfo.
The first parameter, function, is the function which raised the exception. The second parameter, path, will be the
path name passed to function. The third parameter, excinfo, will be the exception information returned by
sys.exc_info(). Exceptions raised by onerror will not be caught.
:param path: The path to remove.
:param ignore_errors: Whether to ignore errors on failed removed or delegate the handling to onerror.
:param onerror: The callback executed when an error on removal is raised.
:param kwargs: Common arguments used to build the SMB Session.
"""
if ignore_errors:
def onerror(*args):
pass
elif onerror is None:
def onerror(*args):
raise
# islink issues SMB requests, so route failures through onerror.
try:
if islink(path, **kwargs):
raise OSError("Cannot call rmtree on a symbolic link")
except OSError:
onerror(islink, path, sys.exc_info())
return
with scandir(path, **kwargs) as scandir_gen:
while True:
try:
dir_entry = next(scandir_gen)
except StopIteration:
break
except OSError:
onerror(scandir, path, sys.exc_info())
continue
# In case the entry is a directory symbolic link we need to remove the dir itself and not recurse down into
# it with rmtree. Doing that would result in a symbolic link target having it's contents removed even if
# it's outside the rmtree scope.
if (
dir_entry.is_symlink()
and dir_entry.stat(follow_symlinks=False).st_file_attributes & FileAttributes.FILE_ATTRIBUTE_DIRECTORY
):
try:
rmdir(dir_entry.path, **kwargs)
except OSError:
onerror(rmdir, dir_entry.path, sys.exc_info())
elif dir_entry.is_dir():
rmtree(dir_entry.path, ignore_errors, onerror, **kwargs)
else:
try:
remove(dir_entry.path, **kwargs)
except OSError:
onerror(remove, dir_entry.path, sys.exc_info())
try:
rmdir(path, **kwargs)
except OSError:
onerror(rmdir, path, sys.exc_info())
def _copy(src, dst, follow_symlinks, copy_meta_func, **kwargs):
# Need to check if dst is a UNC path before checking if it's a dir in smbclient.path before checking to see if it's
# a local directory. If either one is a dir, join the filename of src onto dst.
if (is_remote_path(ntpath.normpath(dst)) and isdir(dst, **kwargs)) or os.path.isdir(dst):
dst = _join_local_or_remote_path(dst, _basename(src))
copyfile(src, dst, follow_symlinks=follow_symlinks, **kwargs)
copy_meta_func(src, dst, follow_symlinks=follow_symlinks, **kwargs)
return dst
def _get_file_stat(path, follow_symlinks=True, **kwargs):
if path.startswith("//") or path.startswith("\\\\"):
return smbclient_stat(path, follow_symlinks=follow_symlinks, **kwargs)
else:
# Source is a local path or accessible to the host, use the builtin os module to get the read only flag.
if follow_symlinks:
return os.stat(path)
else:
return os.lstat(path)
def _set_file_basic_info(file_path, follow_symlinks, read_only=None, atime_ns=None, mtime_ns=None, **kwargs):
co = 0 if follow_symlinks else CreateOptions.FILE_OPEN_REPARSE_POINT
# Need to check if we need to change the attributes if the read_only flag is set. We can't just blindly set the
# read only attribute as that will remove any other attribute set on the file.
new_attributes = 0
if read_only is not None:
file_fd = SMBRawIO(
file_path,
mode="r",
share_access="rw",
create_options=co,
desired_access=FilePipePrinterAccessMask.FILE_READ_ATTRIBUTES,
**kwargs,
)
with SMBFileTransaction(file_fd) as transaction:
query_info(transaction, FileBasicInformation)
existing_attributes = transaction.results[0]["file_attributes"].get_value()
if read_only and existing_attributes & FileAttributes.FILE_ATTRIBUTE_READONLY == 0:
new_attributes = existing_attributes | FileAttributes.FILE_ATTRIBUTE_READONLY
elif not read_only and existing_attributes & FileAttributes.FILE_ATTRIBUTE_READONLY != 0:
new_attributes = existing_attributes & ~FileAttributes.FILE_ATTRIBUTE_READONLY
# Make sure at least 1 attribute is set (normal)
if new_attributes == 0:
new_attributes |= FileAttributes.FILE_ATTRIBUTE_NORMAL
# Only set the attributes if there is actually a change to be made.
if new_attributes or atime_ns is not None or mtime_ns is not None:
file_fd = SMBRawIO(
file_path,
mode="r",
share_access="rw",
create_options=co,
desired_access=FilePipePrinterAccessMask.FILE_WRITE_ATTRIBUTES,
**kwargs,
)
with SMBFileTransaction(file_fd) as transaction:
basic_info = FileBasicInformation()
basic_info["file_attributes"] = new_attributes
if atime_ns is not None:
basic_info["last_access_time"] = int((atime_ns // 100) + DateTimeField.EPOCH_FILETIME)
if mtime_ns is not None:
basic_info["last_write_time"] = int((mtime_ns // 100) + DateTimeField.EPOCH_FILETIME)
set_info(transaction, basic_info)