From c341425aff1c4fc01161c7cb3020d50b3c5d0a87 Mon Sep 17 00:00:00 2001 From: "khaleelhabib02@gmail.com" <115427472+Khaleelhabeeb@users.noreply.github.com> Date: Wed, 27 Mar 2024 18:23:45 +0100 Subject: [PATCH] added docs using mkdocs --- docs/conf.py | 76 ------------------------------ docs/{index.rst => index.md} | 89 +++++++++++++++++++++++------------- mkdocs.yml | 3 ++ 3 files changed, 61 insertions(+), 107 deletions(-) delete mode 100644 docs/conf.py rename docs/{index.rst => index.md} (86%) create mode 100644 mkdocs.yml diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index c96da51..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,76 +0,0 @@ -import os -import sys -sys.path.insert(0, os.path.abspath('..')) # Add parent directory to path for imports - -# -- Project information ----------------------------------------------------- - -project = 'csv-utils' -copyright = '2024, CSV-UTILS(s)' -author = 'Khalil Habib Shariff' - -# The short X.Y version -version = '1.0' -# The full version (including alpha/beta/rc tags) -release = '1.0' - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions shipped with Sphinx, or downloaded extensions. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.napoleon', # For docstrings with Google style - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.linkcode', # Link source code to documentation -] - - -linkcode_base = os.path.abspath('..') - - -napoleon_google_docstring = True -napoleon_numpy_docstring = True - - -templates_path = ['_templates'] - - -source_suffix = '.rst' - - -master_doc = 'index' - - -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - - - -html_theme = 'sphinx_rtd_theme' # Read the Docs theme - - -html_static_path = ['_static'] - - -todo_include_todos = True - - - -autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance'] - - -html_sidebars = { - '**': [ - 'relations.html', - 'navigation.html', - 'searchbox.html', - 'donate.html', - ] -} diff --git a/docs/index.rst b/docs/index.md similarity index 86% rename from docs/index.rst rename to docs/index.md index b7b514d..7323a19 100644 --- a/docs/index.rst +++ b/docs/index.md @@ -1,52 +1,59 @@ -CSV-UTILS DOCUMENTATION -Overview +# CSV-UTILS DOCUMENTATION + csv-util is a Python package designed to facilitate working with CSV files in a more convenient and Pythonic manner compared to the built-in csv module. It provides a set of modules with classes and functions to perform various tasks related to CSV file handling. -Installation +## Installation + You can install csv-util via pip: -pip install csv-utils +```pip install csv-utils ``` -CORE MODULES +## CORE MODULES -Reader -This module contains the Reader class, which extends the functionality of csv.reader. It offers additional features such as automatic type casting, handling missing values, and support for different dialects. +### Reader -from csv_util.reader import Reader +This module contains the Reader class, which extends the functionality of csv.reader. It offers additional features such as automatic type casting, handling missing values, and support for different dialects. -# Example usage +``` from csv_util.reader import Reader ``` -from csv_utils.reader import Reader +### Example usage +```python +from csv_utils.reader import Reader with open('kano.csv', 'r') as file: reader = Reader(file, dialect='excel', type_cast=True, na_values=['', 'NULL']) for row in reader: - print(row) + print(row) -Writer -The writer.py module includes the Writer class, a subclass of csv.writer, enhanced with features like automatic type casting and support for different dialects. +``` + -from csv_util.writer import Writer +### Writer -# Example usage +The writer.py module includes the Writer class, a subclass of csv.writer, enhanced with features like automatic type casting and support for different dialects. +``` from csv_util.writer import Writer ``` + +### Example usage +```python from csv_utils.writer import Writer with open('output.csv', 'w', newline='') as file: writer = Writer(file, dialect='excel', na_rep='NA') writer.writerow([1, 2.5, True, None, 'abc']) writer.writerows([[3, 4.7, False, 'NA', ''], [None, None, True, 'NA', 'xyz']]) +``` +## UTILITY MODULES -UTILITY MODULES +### Manipulation -Manipulation This module provides functions for common operations on CSV data, such as filtering rows, sorting, merging multiple files, and handling headers. -from csv_util.manipulation import filter_rows, sort_rows - -# Example usage +``` from csv_util.manipulation import filter_rows, sort_rows ``` +### Example usage +```python from csv_utils.manipulation import filter_rows, sort_rows, merge_files # Filter rows data = [[1, 2, 3], [4, 5, 6], [7, 8, 9]] @@ -62,15 +69,18 @@ file_paths = ['file1.csv', 'file2.csv', 'file3.csv'] output_path = 'merged.csv' merge_files(file_paths, output_path, dialect='excel', has_header=True) +``` + +### Formatting -Formatting formatting.py includes functions for formatting CSV data, such as adding or removing quotes, handling newlines within fields, and customizing delimiters. -from csv_util.formatting import add_quotes, remove_quotes +``` from csv_util.formatting import add_quotes, remove_quotes ``` -# Example usage +### Example usage +```python import csv from csv_utils.formating import quote_fields, remove_quotes, handle_newlines @@ -89,14 +99,18 @@ data = [['Name', 'Address'], ['John', '123 Main St.\nNew York, NY'], ['Jane', 'F formatted_data = handle_newlines(data, replacement=' ') print(formatted_data) # Output: [['Name', 'Address'], ['John', '123 Main St. New York, NY'], ['Jane', 'Flat 5 London, UK']] +``` + + +### Validation -Validation The validation.py module provides functions to validate CSV data against predefined rules or schemas, ensuring data integrity and consistency. -from csv_util.validation import validate_schema +``` from csv_util.validation import validate_schema ``` -# Example usage +### Example usage +```python from csv_utils.validation import validate_rows, validate_headers # Validate rows data = [[1, 2, 3], [4, 'five', 6], [7, 8, 'nine']] @@ -114,15 +128,19 @@ required_headers = ['Name', 'Age', 'City'] is_valid = validate_headers(headers, required_headers) print(is_valid) # Output: True +``` + + +### conversion -Conversion This module contains functions to convert CSV data to and from other formats like JSON, Excel, SQL tables, etc. -from csv_util.conversion import csv_to_json, json_to_csv +``` from csv_util.conversion import csv_to_json, json_to_csv ``` -# Example usage +### Example usage +```pyhton from csv_utils.conversion import csv_to_json, json_to_csv # CSV to JSON data = [['Name', 'Age', 'City'], ['John', 25, 'New York'], ['Jane', 30, 'London']] @@ -134,8 +152,10 @@ json_data = [{'Name': 'John', 'Age': 25, 'City': 'New York'}, {'Name': 'Jane', ' csv_data = json_to_csv(json_data, headers=['Name', 'Age', 'City']) print(csv_data) # Output: [['Name', 'Age', 'City'], ['John', 25, 'New York'], ['Jane', 30, 'London']] +``` + +### Generation -Generation The generation.py module includes functions to generate CSV files from various data sources, such as dictionaries, databases, or APIs. @@ -143,7 +163,12 @@ from csv_util.generation import generate_from_dict # Example usage +``` from csv_utils.generation import generate_from_db, generate_from_dict ``` + +```python + from csv_utils.generation import generate_from_db, generate_from_dict + # Generate CSV from a dictionary data = {'Name': 'John', 'Age': 25, 'City': 'New York'} output_path = 'output.csv' @@ -161,7 +186,9 @@ db_connection = ...# ... (initialize database connection) output_path = 'output.csv' generate_from_db(query, db_connection, output_path) -Conclusion +``` + +# Conclusion csv-util simplifies CSV file handling in Python by providing a comprehensive set of classes and functions for reading, writing, manipulating, formatting, validating, converting, and generating CSV data. With its intuitive API and enhanced features, csv-util is a valuable tool for data processing tasks involving CSV files. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6319d76 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,3 @@ +site_name: "csv_util Documentation" +nav: + - index.md \ No newline at end of file