# SMB in Python

Read and write files on SMB and Windows shares from Python services.

Your services reach Windows shares and other SMB servers through `self.smb`. Every remote path starts with the name of the share, e.g. `Finance/invoices/2026-08.csv`.

## Upload and download {#upload-and-download}

```python
from zato.server.service import Service

class SyncInvoices(Service):

    def handle(self):

        conn = self.smb['My Share']

        # Upload a local file to the share
        conn.upload('/local/invoices/2026-08.csv', 'Finance/incoming/2026-08.csv')

        # Download a file from the share
        conn.download_file('Finance/reports/summary.csv', '/local/reports/summary.csv')
```

## Read and write remote files directly {#read-and-write-remote-files-directly}

The data is text, bytes, a dict, a list or the service's own input, and the last three are written out as JSON:

```python
from zato.server.service import Service

class ExportOrder(Service):

    def handle(self):

        conn = self.smb['My Share']

        data = self.request.input
        conn.write(data, 'Finance/orders/order-4711.json')

        ack = conn.read('Finance/acks/order-4711.txt')
        self.response.payload = {'ack': ack}
```

## Guaranteed delivery {#guaranteed-delivery}

`.publish` spools the data locally and retries until the share accepts it:

```python
from zato.server.service import Service

class PublishReport(Service):

    def handle(self):

        conn = self.smb['My Share']
        conn.publish(self.request.input, 'Finance/reports/daily.csv')
```

## List and manage directories {#list-and-manage-directories}

Missing parent directories are created along with the one you ask for:

```python
from zato.server.service import Service

class ArchiveInvoices(Service):

    def handle(self):

        conn = self.smb['My Share']

        conn.create_directory('Finance/archive/2026/08')

        for item in conn.list('Finance/incoming'):
            self.logger.info('%s %s', item.name, item.size_human)
            conn.move('Finance/incoming/' + item.name, 'Finance/archive/2026/08/' + item.name)
```

## Configuration {#configuration}

The [enmasse](https://zato.io/docs/admin/enmasse-reference.html#smb) YAML for the connection:

```yaml
smb:
  - name: My Share
    host: files.example.com
    port: 445
    username: zato
    password: Zato_Enmasse_Env.My_Share_Password
```

## See also {#see-also}

- [Connection API](https://zato.io/docs/dev/file-transfer/connection-api.html) - Every method of SFTP and SMB connection objects
- [File transfer schedules](https://zato.io/docs/dev/file-transfer/schedules.html) - Have Zato watch a directory on the share and invoke a service per file
- [SFTP](https://zato.io/docs/dev/examples/sftp.html) - The same API against SFTP servers
- [SharePoint and OneDrive](https://zato.io/docs/dev/examples/cloud/ms365-files.html) - SharePoint and OneDrive files through the Graph API

## Learn more {#learn-more}

- [Development documentation](https://zato.io/docs/dev/) - The complete reference for writing services
- [Requests and responses](https://zato.io/docs/dev/request-response/) - What a service receives, what it returns and how both are structured
- [Integration examples](https://zato.io/docs/dev/examples/) - Ready-made code for the systems you are likely to connect to
- [IDE and debugging](https://zato.io/docs/dev/ide/) - Write services in the Dashboard or in your own editor
- [Data models](https://zato.io/docs/dev/model/) - Declare inputs and outputs and have them validated for you
- [In-depth API tutorial](https://zato.io/tutorials/main/01.html) - The full platform tutorial, from installation to production patterns