From 646cf904e205bf6f164e83c2fe52e4eb80805ad0 Mon Sep 17 00:00:00 2001 From: judahpaul16 Date: Sun, 28 Apr 2024 03:04:28 -0400 Subject: [PATCH] Added docs --- .gitignore | 3 +- docs/api_reference.md | 68 ++++++++++++++++++++++++++++++++++++ docs/getting_started.md | 21 +++++++++++ docs/index.md | 32 +++++++++++++++++ docs/usage/initialization.md | 20 +++++++++++ docs/usage/operations.md | 45 ++++++++++++++++++++++++ mkdocs.yml | 4 +-- 7 files changed, 190 insertions(+), 3 deletions(-) create mode 100644 docs/api_reference.md create mode 100644 docs/getting_started.md create mode 100644 docs/index.md create mode 100644 docs/usage/initialization.md create mode 100644 docs/usage/operations.md diff --git a/.gitignore b/.gitignore index 706c9ea..c23cd5a 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,5 @@ test.py __pycache__ env build -dist \ No newline at end of file +dist +site \ No newline at end of file diff --git a/docs/api_reference.md b/docs/api_reference.md new file mode 100644 index 0000000..90a6aa0 --- /dev/null +++ b/docs/api_reference.md @@ -0,0 +1,68 @@ +# API Reference + +This section provides detailed documentation for all functions and classes available in the Python UrBackup API. + +## Classes + +### `installer_os` + +An enumeration of supported operating systems for installers. + +- `Windows`: Represents a Windows operating system. +- `Linux`: Represents a Linux operating system. + +### `urbackup_server` + +This class provides methods to interact with the UrBackup server. + +#### Attributes + +- `server_basic_username`: Username for basic authentication. +- `server_basic_password`: Password for basic authentication. +- `action_incr_file`: Constant for incremental file backup action. +- `action_full_file`: Constant for full file backup action. +- `action_incr_image`: Constant for incremental image backup action. +- `action_full_image`: Constant for full image backup action. +- `action_resumed_incr_file`: Constant for resumed incremental file backup action. +- `action_resumed_full_file`: Constant for resumed full file backup action. +- `action_file_restore`: Constant for file restore action. +- `action_image_restore`: Constant for image restore action. +- `action_client_update`: Constant for client update action. +- `action_check_db_integrity`: Constant for database integrity check action. +- `action_backup_db`: Constant for database backup action. +- `action_recalc_stats`: Constant for recalculating statistics action. + +#### Methods + +- `__init__(url, username, password)`: Initializes a new `urbackup_server` instance. +- `login()`: Logs in to the UrBackup server and returns `True` on success. +- `get_client_status(client_name)`: Retrieves the status of a specified client. +- `download_installer(installer_fn, new_clientname, os='linux')`: Downloads the installer for a specified client and operating system. +- `add_client(clientname)`: Adds a new client to the server. +- `get_global_settings()`: Retrieves global settings from the server. +- `set_global_setting(key, new_value)`: Sets a global setting on the server. +- `get_client_settings(clientname)`: Retrieves settings for a specified client. +- `change_client_setting(clientname, key, new_value)`: Changes a setting for a specified client. +- `get_client_authkey(clientname)`: Retrieves the authentication key for a specified client. +- `get_server_identity()`: Retrieves the server's identity. +- `get_status()`: Retrieves the overall status of the server. +- `get_livelog(clientid=0)`: Retrieves live log entries for a specified client. +- `get_usage()`: Retrieves usage statistics from the server. +- `get_extra_clients()`: Retrieves a list of extra clients added to the server. +- `start_incr_file_backup(clientname)`: Starts an incremental file backup for a specified client. +- `start_full_file_backup(clientname)`: Starts a full file backup for a specified client. +- `start_incr_image_backup(clientname)`: Starts an incremental image backup for a specified client. +- `start_full_image_backup(clientname)`: Starts a full image backup for a specified client. +- `add_extra_client(addr)`: Adds an extra client by hostname. +- `remove_extra_client(ecid)`: Removes an extra client by ID. +- `get_actions()`: Retrieves current actions being performed on the server. +- `stop_action(action)`: Stops a specific action on the server. + +#### Private Methods + +- `_get_response(action, params, method='POST')`: Sends a request to the server and retrieves the response. +- `_get_json(action, params={})`: Sends a JSON request to the server and parses the response. +- `_download_file(action, outputfn, params)`: Downloads a file from the server based on specified parameters. +- `_md5(s)`: Calculates the MD5 hash of a given string. + +Please refer to the source code for more detailed information on each method, including parameters and expected response types. diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..63a4d5c --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,21 @@ +# Getting Started with Python UrBackup + +## Installation + +To install Python UrBackup, you'll need Python installed on your system. Python UrBackup supports Python 3.x. + +```bash +pip install python-urbackup +``` + +## Configuration + +After installation, you'll need to configure the library with your UrBackup server details: + +```python +from urbackup import urbackup_server + +server = urbackup_server('your_server_url', 'your_username', 'your_password') +``` + +This is the basic configuration needed to start interacting with your UrBackup server. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..0c893b7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,32 @@ +# Python UrBackup ![Icon](https://www.urbackup.org/favicon.ico) + +Python UrBackup is a powerful Python wrapper designed to interact with UrBackup servers. This library allows you to manage backups, restore operations, and monitor the server status programmatically. + +## Features + +- Easy to use Python API. +- Manage and monitor UrBackup server operations. +- Download and configure client installers. + +## Installation + +```bash +pip install python-urbackup +``` + +For more detailed installation instructions, see the [Getting Started](getting_started.md) section. + +## Quick Start + +Here's a quick example to get you started: + +```python +from urbackup import urbackup_server + +# Initialize and log in +server = urbackup_server('your_server_url', 'your_username', 'your_password') +if server.login(): + print("Login successful!") +``` + +For more examples and usage instructions, visit the [Usage](usage/initialization.md) section. diff --git a/docs/usage/initialization.md b/docs/usage/initialization.md new file mode 100644 index 0000000..ce666ef --- /dev/null +++ b/docs/usage/initialization.md @@ -0,0 +1,20 @@ +# Initialization + +To start using the Python UrBackup API, you need to initialize the `urbackup_server` object: + +```python +from urbackup import urbackup_server + +server = urbackup_server('your_server_url', 'your_username', 'your_password') +``` + +## Logging In + +Once the server object is initialized, log in to perform operations: + +```python +if server.login(): + print("Login successful!") +else: + print("Login failed!") +``` \ No newline at end of file diff --git a/docs/usage/operations.md b/docs/usage/operations.md new file mode 100644 index 0000000..7988a11 --- /dev/null +++ b/docs/usage/operations.md @@ -0,0 +1,45 @@ +# Operations + +## Getting Client Status + +To get the status of a specific client: + +```python +client_status = server.get_client_status('client_name') +if client_status: + print(f"Client status: {client_status}") +else: + print("Client not found or access denied.") +``` + +## Downloading an Installer + +To download an installer for a new client: + +```python +if server.download_installer('path/to/installer', 'new_client_name'): + print("Installer downloaded successfully.") +else: + print("Failed to download installer.") +``` + +## Starting Backups + +Start an incremental file backup: + +```python +if server.start_incr_file_backup('client_name'): + print("Incremental file backup started successfully.") +``` + +## Managing Clients + +Add a new client to the server: + +```python +new_client = server.add_client('new_client_name') +if new_client: + print("New client added:", new_client) +else: + print("Failed to add new client.") +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 677e6c8..50a2c72 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,7 +11,7 @@ site_dir: 'site' # Theme configuration theme: - name: mkdocs + name: material color_mode: auto user_color_mode_toggle: true locale: en @@ -39,5 +39,5 @@ plugins: # Extra configuration extra: social: - - type: 'github' + - icon: fontawesome/brands/github link: 'https://github.com/judahpaul16/python-urbackup'