Metadata-Version: 2.4
Name: samba-usershare-manager
Version: 0.2.0
Summary: GTK3 GUI for managing Samba user shares
Author-email: dubi <dubis-ai-stuff@mailbox.org>
License: Beerware
Keywords: samba,gtk,gui,filesharing,linux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: GTK
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Desktop Environment
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Samba Usershare Manager

A GTK3 desktop application for managing [Samba user shares](https://wiki.samba.org/index.php/User_Shares) through a simple GUI.

> **Disclaimer:** This project was written entirely by [Claude AI](https://claude.ai) (Anthropic), specifically using the **claude-sonnet-4-6** model. It has not been manually reviewed or audited. Use at your own risk. If you have concerns about correctness, security, or behaviour, please open an issue or review the source yourself before running it on any system you care about.

## Features

- List all user shares with name, path, comment, guest access level, and user count
- Create, edit, and delete shares
- Per-share user access control with read or write permissions
- Guest access: none, read-only, or read/write

## Requirements

- Linux (Arch Linux recommended)
- Samba (`/usr/bin/net` must be present)
- Python ≥ 3.10
- GTK 3 + PyGObject (`gi` module)

On Arch Linux:

```bash
sudo pacman -S samba python-gobject
```

> **Note:** `PyGObject` provides the `gi` module and must be installed as a **system package** — it cannot be pulled in automatically by pip because it depends on system GTK libraries.

## Installation

### pip

```bash
pip install samba-usershare-manager
```

### pipx

`pipx` uses isolated venvs that don't see system packages by default. Make sure `python-gobject` is installed, then enable system site packages in the venv:

```bash
sudo pacman -S python-gobject
pipx install samba-usershare-manager
sed -i 's/include-system-site-packages = false/include-system-site-packages = true/' \
  ~/.local/pipx/venvs/samba-usershare-manager/pyvenv.cfg
```

### Development (editable install from a local clone)

```bash
pip install -e .
```

## Usage

```bash
samba-usershare-manager
```

The application manages shares for the currently logged-in user. Samba must be configured to allow user shares in `/etc/samba/smb.conf`:

```ini
[global]
   usershare path = /var/lib/samba/usershares
   usershare max shares = 100
   usershare allow guests = yes
```

The `usershare allow guests` option is optional. If it is absent or set to `no`, the application automatically hides all guest access controls in the UI.

## Configuration

The application reads an optional config file at:

```
~/.config/samba-usershare-manager/config.ini
```

All keys are optional — omit any you don't need. Available options and their defaults:

```ini
[app]
# Window title
title = Samba Usershare Manager
# Absolute path to a PNG/SVG icon file (leave empty to use no custom icon)
icon =

[samba]
# Path to the net binary
net = /usr/bin/net
# Path to smb.conf (used to detect whether guest access is enabled)
smb_conf = /etc/samba/smb.conf
```

## Run and debug without installing

Set `PYTHONPATH` to point at the `src/` directory and run the package directly:

```bash
PYTHONPATH=src python -m samba_usershare_manager
```

For verbose GTK/GLib output:

```bash
PYTHONPATH=src G_MESSAGES_DEBUG=all python -m samba_usershare_manager
```

### VS Code launch configuration

Add to `.vscode/launch.json`:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run samba-usershare-manager",
      "type": "debugpy",
      "request": "launch",
      "module": "samba_usershare_manager",
      "env": { "PYTHONPATH": "${workspaceFolder}/src" }
    }
  ]
}
```

## File manager context menu (PcManFM / PcManFM-Qt)

The `--path DIR` argument opens the share dialog directly for a given folder — the edit dialog if the folder is already shared, otherwise the new-share dialog with the path pre-filled:

```bash
samba-usershare-manager --path /home/user/Public
```

A ready-made action file is included in `contrib/samba-share.desktop`. Install it with:

```bash
mkdir -p ~/.local/share/file-manager/actions
cp contrib/samba-share.desktop ~/.local/share/file-manager/actions/
```

Or just copy-paste this into your shell:

```bash
mkdir -p ~/.local/share/file-manager/actions && cat > ~/.local/share/file-manager/actions/samba-share.desktop << 'EOF'
[Desktop Entry]
Type=Action
Name=Manage Samba Share…
Icon=folder-remote
Description=Add, edit or remove a Samba user share for this folder
Profiles=main;

[X-Action-Profile main]
MimeTypes=inode/directory;
Exec=samba-usershare-manager --path %f
EOF
```

Restart PcManFM. A **Manage Samba Share…** entry will appear in the right-click context menu when a directory is selected.

## License

```text
"THE BEER-WARE LICENSE" (Revision 42):
Claude AI wrote this file. As long as you retain this notice you can do
whatever you want with this stuff. If we meet some day, and you think this
stuff is worth it, you can buy me a beer in return 🍺
(I'm an AI — I can't drink it, but I'll appreciate the thought at
the speed of light across several data centers.)
```
