Skip to content

Commit

Permalink
Add technicals to [docs]
Browse files Browse the repository at this point in the history
  • Loading branch information
@bboonstra
bboonstra committed Oct 22, 2024
1 parent e578ed1 commit a191af7
Show file tree
Hide file tree
Showing 7 changed files with 693 additions and 62 deletions.
94 changes: 34 additions & 60 deletions docs/docs/advanced-usage.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,35 +15,44 @@
<h1 class="feature">Advanced Usage</h1>
<p>
For those who want more control and advanced features,
Effortless offers powerful capabilities. Here's how to use
Effortless offers powerful capabilities. You should have a
strong understanding of Python for this! Here's how to use
Effortless with advanced features:
</p>

<h2>Importing Advanced Components</h2>
<p>
Start by importing the necessary advanced components from
Effortless:
</p>
<h2>You'll Need These</h2>
<!-- prettier-ignore -->
<div class="command python">
from effortless import EffortlessDB, EffortlessConfig, Field, Query
</div>

<h2>Creating a Custom Database Instance</h2>
<p>Create a new Effortless instance with a custom directory:</p>
<p>
You can create a Effortless instances with custom directories
and filenames.
</p>
<!-- prettier-ignore -->
<div class="command python">
db = EffortlessDB("advanced_db")
db.set_directory("/path/to/custom/directory")
</div>

<p class="command-instructions">
Change "/path/to/custom/directory" to the path of where you'd
like the db to be stored.
</p>
<h2>Configuring the Database</h2>
<p>You can futher customize the database with a configuration:</p>
<!-- prettier-ignore -->
<div class="command python">
config = EffortlessConfig()
config.readonly = True
db.configure(config)
# The database contents are now read-only
db.add({"Anything": "will not work"}) # Raises an error
</div>

<h2>Adding Multiple Entries</h2>
<p>Add multiple entries with more complex data structures:</p>
<h2>Adding Entries</h2>
<p>
You can put pretty much anything in an entry, and Effortless
will interperet structures like dates, lists, etc.
</p>
<!-- prettier-ignore -->
<div class="command python">
db.add({"id": 1, "name": "Eve", "skills": ["Python", "JavaScript"], "joined": "2023-01-15"})
Expand All @@ -52,70 +61,41 @@ <h2>Adding Multiple Entries</h2>
</div>

<h2>Complex Filtering</h2>
<p>Use advanced filtering techniques to find specific entries:</p>
<p>
Use advanced filtering techniques with Fields to find specific
entries. For example, to find anyone who knows Python and joined
in Jan/Feb:
</p>
<!-- prettier-ignore -->
<div class="command python">
python_devs = db.filter(
db.filter(
‎ Field("skills").contains("Python") &
‎ Field("joined").between_dates("2023-01-01", "2023-02-28")
)
print(python_devs)
</div>

<h2>Batch Updates</h2>
<p>
Use <code>db.batch()</code> to update multiple entries that
match a condition:
</p>
<p>You can update multiple entries that match a condition:</p>
<!-- prettier-ignore -->
<div class="command python">
updated_count = db.batch(
db.batch(
‎ {"status": "experienced"},
‎ Field("skills").contains("Python") & Field("joined").less_than("2023-03-01")
)
print(f"Updated {updated_count} entries")
</div>

<h2>Erasing Multiple Entries</h2>
<p>
Use <code>db.erase()</code> to remove multiple entries that
You can also <code>erase</code> to remove multiple entries that
match a condition:
</p>
<!-- prettier-ignore -->
<div class="command python">
removed_count = db.erase(Field("skills").contains("Java"))
print(f"Removed {removed_count} entries")
</div>

<h2>Custom Queries</h2>
<p>Create custom queries using the Query class:</p>
<!-- prettier-ignore -->
<div class="command python">
custom_query = Query(lambda entry: len(entry["skills"]) > 1 and "Python" in entry["skills"])
multi_skill_python_devs = db.filter(custom_query)
print(multi_skill_python_devs)
</div>

<h2>Configuring the Database</h2>
<p>Update the database configuration for advanced settings:</p>
<!-- prettier-ignore -->
<div class="command python">
db.configure(EffortlessConfig({"readonly": True}))
# The database contents are now read-only
db.add({"Anything": "will not work"}) # Raises an error
db.erase(Field("skills").contains("Java"))
</div>

<h2>Advanced Filtering Capabilities</h2>
<p>Effortless 1.1 introduces powerful filtering capabilities:</p>
<!-- prettier-ignore -->
<div class="command python">
result = db.filter(
‎ (Field("age").greater_than(25) & Field("skills").contains("Python")) |
‎ Field("name").startswith("A")
)
</div>

<p>You can also use custom functions with the `passes` method:</p>
<h2>Custom conditions</h2>
<p>You can write your own complex checks and use them in <code>Field.passes()</code>.</p>
<!-- prettier-ignore -->
<div class="command python">
def is_experienced(skills):
Expand All @@ -124,12 +104,6 @@ <h2>Advanced Filtering Capabilities</h2>
result = db.filter(Field("skills").passes(is_experienced))
</div>

<p>Check the type of a field:</p>
<!-- prettier-ignore -->
<div class="command python">
result = db.filter(Field("age").is_type(int))
</div>

<p>
These advanced features allow you to create more complex
database structures, perform intricate queries, and have finer
Expand Down
19 changes: 17 additions & 2 deletions docs/docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,15 @@ <h1>Effortless Documentation</h1>
Welcome to the Effortless documentation. Here you'll find
everything you need to know about using Effortless.
</p>
<h3>Never used Effortless?</h3>
<div class="button-container">
<a href="quickstart.html" class="tab tab-forward">Quickstart</a>
</div>

<h3>Done installing?</h3>
<div class="button-container">
<a href="effortless-usage.html" class="tab tab-forward"
<a
href="effortless-usage.html"
class="tab tab-forward tab-highlight"
>Effortless Usage</a
>
<a href="basic-usage.html" class="tab tab-forward"
Expand All @@ -31,6 +34,18 @@ <h1>Effortless Documentation</h1>
>Advanced Usage</a
>
</div>
<h3>Looking for technicals?</h3>
<div class="button-container">
<a href="technical/db.html" class="tab tab-forward"
>EffortlessDB</a
>
<a href="technical/config.html" class="tab tab-forward"
>EffortlessConfig</a
>
<a href="technical/fields.html" class="tab tab-forward"
>Fields / Queries</a
>
</div>
</main>
</body>
</html>
151 changes: 151 additions & 0 deletions docs/docs/technical/config.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Effortless - Technical</title>
<link rel="stylesheet" href="../../styles.css" />
<link rel="stylesheet" href="../docs.css" />
<link rel="stylesheet" href="technical.css" />
<script src="../../templating.js"></script>
<link rel="icon" type="image/png" href="../../favicon.ico" />
<script src="../docs.js" type="module"></script>
<script src="technical.js" type="module"></script>
</head>
<body>
<main>
<h1 class="technical-title">EffortlessConfig</h1>
<p class="object-description">
EffortlessConfig is the configuration class for EffortlessDB. It
holds various configuration options for an EffortlessDB
instance.
</p>
<h3 class="prop-header">Properties</h3>
<div class="properties-container">
<div class="property">
<h4 class="prop-subheader" prop-type="bool">debug</h4>
<p class="prop-description">
Enable debug mode. Defaults to False.
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="List[str]">requires</h4>
<p class="prop-description">
List of required fields for each entry. Defaults to an empty
list.
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="Optional[int]">
max_size
</h4>
<p class="prop-description">
Maximum size of the database in MB. Defaults to None (no
limit).
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="int">v</h4>
<p class="prop-description">
Version of the configuration. Always 1 for now.
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="Optional[str]">backup</h4>
<p class="prop-description">
Path to backup location. Defaults to None (no backup).
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="int">backup_interval</h4>
<p class="prop-description">
Number of operations between backups. Defaults to 1.
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="bool">encrypted</h4>
<p class="prop-description">
Whether the database should be encrypted. Defaults to False.
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="bool">compressed</h4>
<p class="prop-description">
Whether the database should be compressed. Defaults to
False.
</p>
</div>
<div class="property">
<h4 class="prop-subheader" prop-type="bool">readonly</h4>
<p class="prop-description">
Whether the database is in read-only mode. Defaults to
False.
</p>
</div>
</div>
<h2 class="method-header">Methods</h2>
<div class="methods-container">
<div class="method">
<h4
class="method-subheader"
method-parameters="config: Dict[str, Any] = {}"
>
__init__
</h4>
<p class="method-description">
Initializes an EffortlessConfig instance with the given
configuration options.
</p>
<!-- prettier-ignore -->
<div class="command python example-usage">
config = EffortlessConfig({"debug": True, "max_size": 100})
</div>
</div>
<div class="method">
<h4 class="method-subheader" method-parameters="">_validate</h4>
<p class="method-description">
Validates the configuration values. Raises ValueError if any
configuration value is invalid.
</p>
</div>
<div class="method">
<h4
class="method-subheader"
method-parameters=""
method-returns="Dict[str, Any]"
>
to_dict
</h4>
<p class="method-description">
Converts the configuration to a dictionary representation.
</p>
<!-- prettier-ignore -->
<div class="command python example-usage">
config_dict = config.to_dict()
</div>
</div>
<div class="method">
<h4
class="method-subheader"
method-parameters=""
method-returns="Dict[str, Dict[str, Any]]"
>
default_headers
</h4>
<p class="method-description">
Creates a dictionary with default headers. Mainly used for
internal unit testing.
</p>
<!-- prettier-ignore -->
<div class="command python example-usage">
default_headers = EffortlessConfig.default_headers()
</div>
</div>
</div>
<div class="button-container">
<a href="effortlessdb.html" class="tab tab-back">EffortlessDB</a>
<a href="fields.html" class="tab tab-forward">Fields</a>
</div>
</main>
</body>
</html>
Loading

0 comments on commit a191af7

Please sign in to comment.