Updated README.

Author: freddieknets

README.md

@@ -2,6 +2,7 @@
 
 Xaux is a package with support tools, both for general usage and tune for CERN / Xsuite usage. It is thoroughly tested for all python versions from 3.8 onwards, to ensure stability. The following tools are provided:
 
+
 ### Singleton
 The decorator `@singleton` will redefine a class into a singleton such that only one instance exists and the same instance is returned every time the class is instantiated.
 
@@ -11,6 +12,30 @@ The decorator `@singleton` will redefine a class into a singleton such that only
 - The singleton can be reset by calling the `delete()` method of the class, which will invalidate any existing instances.
 - The decorator provides a `get_self()` method, which is a class method that is more relaxed than the constructor, as it allows passing any `**kwargs` even if they aren't attributes for the singleton (these  will then just be ignored). This is useful for kwargs filtering in getters or specific functions.
 
+Example usage:
+
+```python
+@singleton
+class MyClass:
+
+    def __init__(self, value=10):
+        self.value = value
+```
+```python
+>>> instance1 = MyClass(value=8)
+>>> instance2 = MyClass(value=9)
+>>> print(instance1.value)
+9
+>>> print(instance2.value)
+9
+>>> print(instance1 is instance2)
+True
+>>> instance3 = MyClass()
+>>> print(instance1.value)
+9
+```
+
+
 ### Class Property
 The descriptor `@ClassProperty` works similar as `@property` but is used to define class properties (instead of instance properties).
 
@@ -29,16 +54,35 @@ class MyClass(metaclass=ClassPropertyMeta):
 
     @ClassProperty
     def my_class_property(cls):
+        print("In getter")
         return cls._my_classproperty
 
     @my_class_property.setter
     def my_class_property(cls, value):
+        print("In setter")
         cls._my_classproperty = value
 
     @my_class_property.deleter
     def my_class_property(cls):
+        print("In deleter")
         cls._my_classproperty = 0
 ```
+```python
+>>> print(MyClass.my_class_property)
+In getter
+0
+>>> MyClass.my_class_property = 3
+In setter
+>>> print(MyClass.my_class_property)
+In getter
+3
+>>> del MyClass.my_class_property
+In deleter
+>>> print(MyClass.my_class_property)
+In getter
+0
+```
+
 
 ### FsPath
 This is an extension to the `Path` class from `pathlib`, which is adapted to work, besides on regular local file systems, robustly and efficiently on AFS (the Andrew File System) and EOS (a storage-oriented file system developed at CERN). It defines three classes, `LocalPath`, `AfsPath`, and `EosPath`, and a class factory `FsPath`. The correct class will be automatically instantiated based on the file system on which the path sits. Care is taken to correctly resolve a path when symlinks are present.
@@ -47,14 +91,27 @@ The main advantage is that for a whole set of file operations, the standard `Pat
 
 Note that `LocalPath` is just a regular `Path` but with additional access to the `FsPath` methods.
 
-### General Tools
-These are a set of lightweight tools:
- - `timestamp` provides an easy way to get timestamps into logs and filenames (with second, millisecond, or microsecond accuracy).
- - `ranID` generates a Base64 encoded random ID string, useful for in filenames or element names.
- - `system_lock` is typically used for a cronjob. It will exit the python process if the previous cronjob did not yet finish (based on a custom lockfile name).
- - `get_hash` is a quick way to hash a file, in chunks of a given size.
+Example usage:
+
+```python
+>>> path = FsPath('/newhome/fvanderv/work')  # 'work' is a symbolic link on a local file system that points to an AFS folder
+>>> path
+LocalPosixPath('/newhome/fvanderv/work')
+>>> path.resolve()
+AfsPosixPath('/afs/cern.ch/work/f/fvanderv')
+```
+```python
+>>> path = FsPath('/eos/project/c/collimation-team')
+>>> path
+EosPosixPath('/eos/project/c/collimation-team')
+>>> path.eos_path # EosPath objects have a few specific attributes that correctly resolve EOS components
+/eos/project/c/collimation-team
+>>> path.eos_path_full
+root://eosproject.cern.ch//eos/project/c/collimation-team
+>>> path.eos_instance
+project
+```
 
-Then there are also a few tools to get info about a function's arguments, which are only accessible via `xaux.tools` and are essentially just wrappers around functions in `inspect`. These are `count_arguments`, `count_required_arguments`, `count_optional_arguments`, `has_variable_length_arguments`, `has_variable_length_positional_arguments`, and `has_variable_length_keyword_arguments`.
 
 ### ProtectFile
 This is a wrapper around a file pointer, protecting it with a lockfile. It is meant to be used inside a context, where the entering and leaving of a context ensures file protection. The moment the object is instantiated, a lockfile is generated (which is destroyed after leaving the context). Attempts to access the file will be postponed as long as a lockfile exists. Furthermore, while in the context, file operations are done on a temporary file, that is only moved back when leaving the context.
@@ -65,6 +122,29 @@ Several systems are in place to (almost) completely rule out concurrency and rac
 
 The tool works particularly well on EOS using the FsPath mechanics, however, on AFS it cannot be used reliably as different node servers can be out-of-sync with each other for a few seconds up to minutes.
 
+Example usage:
+
+```python
+import json
+from xaux import ProtectFile
+with ProtectFile(info.json, 'r+', wait=1) as pf:
+    meta = json.load(pf)
+    meta.update({'author': 'Emperor Claudius'})
+    pf.truncate(0)          # Delete file contents (to avoid appending)
+    pf.seek(0)              # Move file pointer to start of file
+    json.dump(meta, pf, indent=2, sort_keys=False))
+```
+
+### General Tools
+These are a set of lightweight tools:
+ - `timestamp` provides an easy way to get timestamps into logs and filenames (with second, millisecond, or microsecond accuracy).
+ - `ranID` generates a Base64 encoded random ID string, useful for in filenames or element names.
+ - `system_lock` is typically used for a cronjob. It will exit the python process if the previous cronjob did not yet finish (based on a custom lockfile name).
+ - `get_hash` is a quick way to hash a file, in chunks of a given size.
+
+Then there are also a few tools to get info about a function's arguments, which are only accessible via `xaux.tools` and are essentially just wrappers around functions in `inspect`. These are `count_arguments`, `count_required_arguments`, `count_optional_arguments`, `has_variable_length_arguments`, `has_variable_length_positional_arguments`, and `has_variable_length_keyword_arguments`.
+
+
 ### Dev Tools for Xsuite
 These are tools used for the maintenance and deployment of python packages. They are not in the test suite, and only accessible via `xaux.dev_tools`. The low-level functionality is a set of wrappers around `gh` (GitHub CLI), `git`, and `poetry`, while the higher-level functions are `make_release`, `make_release_branch`, `rename_release_branch` which are tailored to Xsuite and go through the same sequence of steps (verifying the release version number, making a PR to main, accepting it, publishing to PyPi, and making draft release notes on GitHub), while asserting the local workspace is clean and asking confirmation at each step. These are currently used as the default tools to maintain and deploy `xaux`, `xboinc`, `xcoll`, and `xdyna`.