Skip to content

Commit

Permalink
refactor: #96 Improve documentation comments for ManagedDirectory and…
Browse files Browse the repository at this point in the history 
… DirectoryOps classes
  • Loading branch information
@sonoh5n
sonoh5n committed Jan 14, 2025
1 parent bdff1bc commit 02a2043
Showing 1 changed file with 102 additions and 101 deletions.
203 changes: 102 additions & 101 deletions rdetoolkit-core/fsops.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,19 +28,19 @@ fn map_io_err(e: &IoError, context: &str, path: &Path) -> PyErr {
}

#[pyclass]
/// A directory manager that handles index-based subdirectories.
///
/// This class manages a directory structure that can include indexed subdirectories
/// under a 'divided' folder. The directory path is constructed as:
/// - For idx=0: {base_dir}/{dirname}
/// - For idx>0: {base_dir}/divided/{idx:0{n_digit}d}/{dirname}
///
/// Example:
/// >>> dir = ManagedDirectory("/path/to/base", "docs")
/// >>> dir.path # "/path/to/base/docs"
/// >>> dir2 = dir(1) # Creates "/path/to/base/divided/0001/docs"
#[derive(Clone)]
pub struct ManagedDirectory {
// A directory manager that handles index-based subdirectories.
//
// This class manages a directory structure that can include indexed subdirectories
// under a 'divided' folder. The directory path is constructed as:
// - For idx=0: {base_dir}/{dirname}
// - For idx>0: {base_dir}/divided/{idx:0{n_digit}d}/{dirname}
//
// Example:
// >>> dir = ManagedDirectory("/path/to/base", "docs")
// >>> dir.path # "/path/to/base/docs"
// >>> dir2 = dir(1) # Creates "/path/to/base/divided/0001/docs"
base_dir: PathBuf,
dirname: String,
n_digit: usize,
Expand All @@ -52,27 +52,27 @@ pub struct ManagedDirectory {
#[pymethods]
impl ManagedDirectory {
#[new]
/// Create a new ManagedDirectory instance.
///
/// Args:
/// base_dir (str): Base directory path
/// dirname (str): Name of the directory to manage
/// n_digit (int, optional): Number of digits for index formatting. Defaults to 4
/// idx (int, optional): Initial index. Defaults to 0
///
/// Returns:
/// ManagedDirectory: New instance
///
/// Raises:
/// ValueError: If dirname is empty
/// OSError: If directory creation fails
#[pyo3(signature = (base_dir, dirname, n_digit=None, idx=None))]
fn new(
base_dir: &str,
dirname: &str,
n_digit: Option<usize>,
idx: Option<i32>,
) -> PyResult<Self> {
// Create a new ManagedDirectory instance.
//
// Args:
// base_dir (str): Base directory path
// dirname (str): Name of the directory to manage
// n_digit (int, optional): Number of digits for index formatting. Defaults to 4
// idx (int, optional): Initial index. Defaults to 0
//
// Returns:
// ManagedDirectory: New instance
//
// Raises:
// ValueError: If dirname is empty
// OSError: If directory creation fails
let n_digit = n_digit.unwrap_or(4);
let idx = idx.unwrap_or(0);
let base_dir = PathBuf::from(base_dir);
Expand All @@ -90,7 +90,7 @@ impl ManagedDirectory {
divided_dir.join(dirname)
};

fs::create_dir_all(&path).map_err(|e| map_io_err(&e, "create_dir_all", &path))?;
// fs::create_dir_all(&path).map_err(|e| map_io_err(&e, "create_dir_all", &path))?;

Ok(ManagedDirectory {
base_dir,
Expand All @@ -102,32 +102,33 @@ impl ManagedDirectory {
}

#[getter]
/// Get the full path of the managed directory.
///
/// Returns:
/// str: Full path as string
fn get_path(&self) -> PyResult<String> {
// Get the full path of the managed directory.
//
// Returns:
// str: Full path as string
fs::create_dir_all(&self.path).map_err(|e| map_io_err(&e, "create_dir_all", &self.path))?;
Ok(self.path.to_string_lossy().to_string())
}

/// Create the managed directory if it doesn't exist.
///
/// Raises:
/// OSError: If directory creation fails
fn create(&self) -> PyResult<()> {
// Create the managed directory if it doesn't exist.
//
// Raises:
// OSError: If directory creation fails
fs::create_dir_all(&self.path).map_err(|e| map_io_err(&e, "create_dir_all", &self.path))?;
Ok(())
}

/// List all files and directories in the managed directory.
///
/// Returns:
/// list[str]: List of paths as strings
///
/// Raises:
/// FileNotFoundError: If the directory does not exist
/// OSError: If reading the directory fails
fn list(&self) -> PyResult<Vec<String>> {
// List all files and directories in the managed directory.
//
// Returns:
// list[str]: List of paths as strings
//
// Raises:
// FileNotFoundError: If the directory does not exist
// OSError: If reading the directory fails
if !self.path.exists() {
return Err(PyFileNotFoundError::new_err(format!(
"Directory does not exist: {}",
Expand All @@ -145,19 +146,19 @@ impl ManagedDirectory {
Ok(result)
}

/// Create a new ManagedDirectory instance with the specified index.
///
/// Args:
/// idx (int): Index for the new directory
///
/// Returns:
/// ManagedDirectory: New instance with the specified index
///
/// Raises:
/// ValueError: If idx is negative
/// OSError: If directory creation fails
#[pyo3(signature = (idx))]
fn __call__(&self, idx: i32) -> PyResult<Self> {
// Create a new ManagedDirectory instance with the specified index.
//
// Args:
// idx (int): Index for the new directory
//
// Returns:
// ManagedDirectory: New instance with the specified index
//
// Raises:
// ValueError: If idx is negative
// OSError: If directory creation fails
if idx < 0 {
return Err(PyValueError::new_err("Index must be non-negative"));
}
Expand All @@ -173,7 +174,7 @@ impl ManagedDirectory {
divided_dir.join(&self.dirname)
};

fs::create_dir_all(&path).map_err(|e| map_io_err(&e, "create_dir_all (call)", &path))?;
// fs::create_dir_all(&path).map_err(|e| map_io_err(&e, "create_dir_all (call)", &path))?;

Ok(Self {
base_dir: self.base_dir.clone(),
Expand All @@ -194,39 +195,39 @@ impl ManagedDirectory {
}

#[pyclass]
/// A utility class for managing multiple directories with support for indexed subdirectories.
///
/// This class provides functionality to:
/// - Create and manage base directories
/// - Create indexed subdirectories under a 'divided' folder
/// - Access directories via attribute-style notation
///
/// Example:
/// >>> ops = DirectoryOps("/path/to/base")
/// >>> ops.invoice # Creates "/path/to/base/invoice"
/// >>> ops.all(2) # Creates base dirs and divided/0001, divided/0002 subdirs
#[derive(Clone)]
pub struct DirectoryOps {
// A utility class for managing multiple directories with support for indexed subdirectories.
//
// This class provides functionality to:
// - Create and manage base directories
// - Create indexed subdirectories under a 'divided' folder
// - Access directories via attribute-style notation
//
// Example:
// >>> ops = DirectoryOps("/path/to/base")
// >>> ops.invoice # Creates "/path/to/base/invoice"
// >>> ops.all(2) # Creates base dirs and divided/0001, divided/0002 subdirs
base_dir: PathBuf,
n_digit: usize,
}

#[pymethods]
impl DirectoryOps {
#[new]
/// Create a new DirectoryOps instance.
///
/// Args:
/// base_dir (str): Base directory path
/// n_digit (int, optional): Number of digits for index formatting. Defaults to 4
///
/// Returns:
/// DirectoryOps: New instance
///
/// Raises:
/// OSError: If directory creation fails
#[pyo3(signature = (base_dir, n_digit=None))]
fn new(base_dir: &str, n_digit: Option<usize>) -> PyResult<Self> {
// Create a new DirectoryOps instance.
//
// Args:
// base_dir (str): Base directory path
// n_digit (int, optional): Number of digits for index formatting. Defaults to 4
//
// Returns:
// DirectoryOps: New instance
//
// Raises:
// OSError: If directory creation fails
let n_digit = n_digit.unwrap_or(4);
let base_dir = PathBuf::from(base_dir);

Expand All @@ -236,20 +237,20 @@ impl DirectoryOps {
Ok(DirectoryOps { base_dir, n_digit })
}

/// Create a ManagedDirectory instance for the given directory name.
///
/// Args:
/// name (str): Name of the directory to manage
///
/// Returns:
/// ManagedDirectory: New instance for the requested directory
///
/// Raises:
/// OSError: If directory creation fails
fn __getattr__(&self, name: &str) -> PyResult<ManagedDirectory> {
// Create a ManagedDirectory instance for the given directory name.
//
// Args:
// name (str): Name of the directory to manage
//
// Returns:
// ManagedDirectory: New instance for the requested directory
//
// Raises:
// OSError: If directory creation fails
let path = self.base_dir.join(name);

fs::create_dir_all(&path).map_err(|e| map_io_err(&e, "create_dir_all(subdir)", &path))?;
// fs::create_dir_all(&path).map_err(|e| map_io_err(&e, "create_dir_all(subdir)", &path))?;

Ok(ManagedDirectory {
base_dir: self.base_dir.clone(),
Expand All @@ -260,22 +261,22 @@ impl DirectoryOps {
})
}

/// Create all supported directories and optionally their indexed subdirectories.
///
/// When idx is specified, creates indexed subdirectories under 'divided' folder
/// for supported directory types.
///
/// Args:
/// idx (int, optional): Maximum index for divided subdirectories
///
/// Returns:
/// list[str]: List of created directory paths
///
/// Raises:
/// ValueError: If idx is negative
/// OSError: If directory creation fails
#[pyo3(signature = (idx=None))]
fn all(&self, idx: Option<i32>) -> PyResult<Vec<String>> {
// Create all supported directories and optionally their indexed subdirectories.
//
// When idx is specified, creates indexed subdirectories under 'divided' folder
// for supported directory types.
//
// Args:
// idx (int, optional): Maximum index for divided subdirectories
//
// Returns:
// list[str]: List of created directory paths
//
// Raises:
// ValueError: If idx is negative
// OSError: If directory creation fails
let base_only_dirs = vec!["invoice", "invoice_patch", "attachment", "tasksupport"];
let divided_supported_dirs = vec![
"structured",
Expand Down

0 comments on commit 02a2043

Please sign in to comment.