Merge pull request #114 from ThomasWaldmann/fix-typos-grammar

fix typos / grammar

Author: ThomasWaldmann

CHANGES.rst

@@ -1,4 +1,4 @@
-ChangeLog
+Changelog
 =========
 
 Version 0.3.0 2025-05-22
@@ -12,13 +12,13 @@ New features:
 
   - operation
   - name(s)
-  - params like deleted
+  - parameters such as deleted
   - size and timing
 
   Please note:
 
-  - logging is done at debug level, so log output is not visible with a default logger.
-  - borgstore does not configure logging, that is the task of the application that uses borgstore.
+  - logging is done at DEBUG level, so log output is not visible with a default logger.
+  - borgstore does not configure logging; that is the task of the application that uses borgstore.
 
 
 Version 0.2.0 2025-04-21
@@ -28,8 +28,8 @@ Breaking changes:
 
 - Store.list: changed deleted argument semantics, #83:
 
-  - True: list ONLY soft deleted items
-  - False: list ONLY not soft deleted items
+  - True: list ONLY soft-deleted items
+  - False: list ONLY non-deleted items
 
 New features:
 
@@ -40,14 +40,14 @@ New features:
 Bug fixes:
 
 - rclone: fix discard thread issues, #92
-- rclone: check rclone regex before raising rclone related exceptions
+- rclone: check rclone regex before raising rclone-related exceptions
 
 Other changes:
 
-- posixfs: also support windows file:/// URLs, #82
-- posixfs / sftp: optimize mkdir usage, add retry, #85
+- posixfs: also support Windows file:/// URLs, #82
+- posixfs / sftp: optimize mkdir usage, add retries, #85
 - posixfs / sftp: change .precreate_dirs default to False
-- rclone init: use a random port instead on relying on rclone to pick one
+- rclone init: use a random port instead of relying on rclone to pick one
 
 
 Version 0.1.0 2024-10-15
@@ -62,7 +62,7 @@ Other changes:
 
 - sftp/posixfs backends: remove ad-hoc mkdir calls, #46
 - optimize Sftp._mkdir, #80
-- sftp backend is now optional, avoids dependency issues on some platforms, #74.
+- sftp backend is now optional, avoiding dependency issues on some platforms, #74.
   Use pip install "borgstore[sftp]" to install with the sftp backend.
 
 
@@ -94,8 +94,8 @@ Other changes:
 Version 0.0.4 2024-09-22
 ------------------------
 
-- rclone: new backend to access any of the 100s of cloud backends rclone
-  supports, needs rclone >= v1.57.0.
+- rclone: new backend to access any of the 100s of cloud backends that rclone
+  supports; needs rclone >= v1.57.0.
 
   See the rclone docs for installing rclone and creating remotes.
   After that, borgstore will support URLs like:
@@ -104,10 +104,10 @@ Version 0.0.4 2024-09-22
   - rclone://remote:path
   - rclone:///tmp/testdir (local fs, for testing)
 - Store.list: give up trying to do anything with a directory's "size"
-- .info / .list: return st.st_size for a directory "as is"
+- .info / .list: return st.st_size for a directory "as-is"
 - tests: BORGSTORE_TEST_RCLONE_URL to set rclone test URL
-- tests: allow BORGSTORE_TEST_*_URL into testenv to make tox work
-  for testing sftp, rclone or other URLs.
+- tests: allow BORGSTORE_TEST_*_URL in the testenv to make tox work
+  for testing sftp, rclone, or other URLs.
 
 
 Version 0.0.3 2024-09-17
@@ -116,7 +116,7 @@ Version 0.0.3 2024-09-17
 - sftp: add support for ~/.ssh/config, #37
 - sftp: username is optional, #27
 - load known_hosts, remove AutoAddPolicy, #39
-- store: raise BE specific exceptions, #34
+- store: raise backend-specific exceptions, #34
 - add Store.stats property, #25
 - bandwidth emulation via BORGSTORE_BANDWIDTH [bit/s], #24
 - latency emulation via BORGSTORE_LATENCY [us], #24
@@ -129,10 +129,10 @@ Version 0.0.2 2024-09-10
 
 - sftp backend: use paramiko's client.posix_rename, #17
 - posixfs backend: hack: accept file://relative/path, #23
-- support / test on Python 3.13, #21
+- support and test on Python 3.13, #21
 
 
 Version 0.0.1 2024-08-23
 ------------------------
 
-First PyPi release.
+First PyPI release.

README.rst

@@ -8,25 +8,25 @@ Keys
 
 A key (str) can look like:
 
-- 0123456789abcdef...  (usually a long, hex-encoded hash value)
-- Any other pure ASCII string without "/" or ".." or " ".
+- 0123456789abcdef... (usually a long, hex-encoded hash value)
+- Any other pure ASCII string without '/', '..', or spaces.
 
 
 Namespaces
 ----------
 
-To keep stuff apart, keys should get prefixed with a namespace, like:
+To keep things separate, keys should be prefixed with a namespace, such as:
 
 - config/settings
 - meta/0123456789abcdef...
 - data/0123456789abcdef...
 
 Please note:
 
-1. you should always use namespaces.
-2. nested namespaces like namespace1/namespace2/key are not supported.
-3. the code could work without a namespace (namespace ""), but then you
-   can't add another namespace later, because then you would have created
+1. You should always use namespaces.
+2. Nested namespaces like namespace1/namespace2/key are not supported.
+3. The code can work without a namespace (empty namespace ""), but then you
+   can't add another namespace later, because that would create
    nested namespaces.
 
 Values
@@ -38,20 +38,20 @@ Store Operations
 ----------------
 
 The high-level Store API implementation transparently deals with nesting and
-soft deletion, so the caller doesn't have to care much for that and the Backend
+soft deletion, so the caller doesn't have to care much about that, and the backend
 API can be much simpler:
 
 - create/destroy: initialize or remove the whole store.
-- list: flat list of the items in the given namespace (by default only not
-  soft deleted items, optionally only soft deleted items).
-- store: write a new item into the store (giving its key/value pair)
-- load: read a value from the store (giving its key), partial loads giving
-  offset and/or size are supported.
-- info: get information about an item via its key (exists? size? ...)
-- delete: immediately remove an item from the store (giving its key)
-- move: implements rename, soft delete / undelete, move to current
-  nesting level
-- stats: api call counters, time spent in api methods, data volume/throughput
+- list: flat list of the items in the given namespace (by default, only non-deleted
+  items; optionally, only soft-deleted items).
+- store: write a new item into the store (providing its key/value pair).
+- load: read a value from the store (given its key); partial loads specifying
+  an offset and/or size are supported.
+- info: get information about an item via its key (exists, size, ...).
+- delete: immediately remove an item from the store (given its key).
+- move: implements rename, soft delete/undelete, and moving to the current
+  nesting level.
+- stats: API call counters, time spent in API methods, data volume/throughput.
 - latency/bandwidth emulator: can emulate higher latency (via BORGSTORE_LATENCY
   [us]) and lower bandwidth (via BORGSTORE_BANDWIDTH [bit/s]) than what is
   actually provided by the backend.
@@ -61,15 +61,14 @@ Store operations (and per-op timing and volume) are logged at DEBUG log level.
 Automatic Nesting
 -----------------
 
-For the Store user, items have names like e.g.:
+For the Store user, items have names such as:
 
 - namespace/0123456789abcdef...
 - namespace/abcdef0123456789...
 
 If there are very many items in the namespace, this could lead to scalability
-issues in the backend, thus the Store implementation offers transparent
-nesting, so that internally the Backend API will be called with
-names like e.g.:
+issues in the backend. The Store implementation therefore offers transparent
+nesting, so that internally the backend API is called with names such as:
 
 - namespace/01/23/56/0123456789abcdef...
 - namespace/ab/cd/ef/abcdef0123456789...
@@ -80,68 +79,68 @@ there can be different nesting configurations depending on the namespace.
 The Store supports operating at different nesting levels in the same
 namespace at the same time.
 
-When using nesting depth > 0, the backends will assume that keys are hashes
-(have hex digits) because some backends will want to pre-create the nesting
-directories at backend initialization time to optimize for better performance
-while using the backend.
+When using nesting depth > 0, the backends assume that keys are hashes
+(contain hex digits) because some backends pre-create the nesting
+directories at initialization time to optimize performance while using the backend.
 
 Soft deletion
 -------------
 
-To soft delete an item (so its value could be still read or it could be
+To soft delete an item (so its value can still be read or it can be
 undeleted), the store just renames the item, appending ".del" to its name.
 
 Undelete reverses this by removing the ".del" suffix from the name.
 
 Some store operations have a boolean flag "deleted" to choose whether they
-shall consider soft deleted items.
+should consider soft-deleted items.
 
 Backends
 --------
 
-The backend API is rather simple, one only needs to provide some very
+The backend API is rather simple; one only needs to provide some very
 basic operations.
 
-Existing backends are listed below, more might come in future.
+Existing backends are listed below; more might come in the future.
 
 posixfs
 ~~~~~~~
 
 Use storage on a local POSIX filesystem:
 
 - URL: ``file:///absolute/path``
-- it is the caller's task to create an absolute fs path from a relative one.
-- namespaces: directories
-- values: in key-named files
+- It is the caller's responsibility to convert a relative path into an absolute
+  filesystem path.
+- Namespaces: directories
+- Values: in key-named files
 
 sftp
 ~~~~
 
-Use storage on a sftp server:
+Use storage on an SFTP server:
 
 - URL: ``sftp://user@server:port/relative/path`` (strongly recommended)
 
-  For user's and admin's convenience, mapping the URL path to the server fs path
+  For users' and admins' convenience, mapping the URL path to the server filesystem path
   depends on the server configuration (home directory, sshd/sftpd config, ...).
   Usually the path is relative to the user's home directory.
 - URL: ``sftp://user@server:port//absolute/path``
 
-  As this uses an absolute path, things are more difficult here:
+  As this uses an absolute path, some things are more difficult:
 
-  - user's config might break if server admin moves a user home to a new location.
-  - users must know the full absolute path of space they have permission to use.
-- namespaces: directories
-- values: in key-named files
+  - A user's configuration might break if a server admin moves a user's home to a new location.
+  - Users must know the full absolute path of the space they have permission to use.
+- Namespaces: directories
+- Values: in key-named files
 
 rclone
 ~~~~~~
 
 Use storage on any of the many cloud providers `rclone <https://rclone.org/>`_ supports:
 
-- URL: ``rclone:remote:path``, we just prefix "rclone:" and give all to the right
-  of that to rclone, see: https://rclone.org/docs/#syntax-of-remote-paths
-- implementation of this primarily depends on the specific remote.
-- rclone binary path can be set via the environment variable RCLONE_BINARY (default value: "rclone")
+- URL: ``rclone:remote:path`` — we just prefix "rclone:" and pass everything to the right
+  of that to rclone; see: https://rclone.org/docs/#syntax-of-remote-paths
+- The implementation primarily depends on the specific remote.
+- The rclone binary path can be set via the environment variable ``RCLONE_BINARY`` (default: "rclone").
 
 
 s3
@@ -165,25 +164,25 @@ Use storage on an S3-compliant cloud service:
   .. note::
 
      There is a known issue with some S3-compatible services (e.g., **Backblaze B2**).
-     If you encounter problems, try using ``b2:`` instead of ``s3:`` in the url.
+     If you encounter problems, try using ``b2:`` instead of ``s3:`` in the URL.
 
-- namespaces: directories
-- values: in key-named files
+- Namespaces: directories
+- Values: in key-named files
 
 
 Scalability
 -----------
 
 - Count of key/value pairs stored in a namespace: automatic nesting is
   provided for keys to address common scalability issues.
-- Key size: there are no special provisions for extremely long keys (like:
-  more than backend limitations). Usually this is not a problem though.
+- Key size: there are no special provisions for extremely long keys (e.g.,
+  exceeding backend limitations). Usually this is not a problem, though.
 - Value size: there are no special provisions for dealing with large value
-  sizes (like: more than free memory, more than backend storage limitations,
+  sizes (e.g., more than available memory, more than backend storage limitations,
   etc.). If one deals with very large values, one usually cuts them into
-  chunks before storing them into the store.
+  chunks before storing them in the store.
 - Partial loads improve performance by avoiding a full load if only a part
-  of the value is needed (e.g. a header with metadata).
+  of the value is needed (e.g., a header with metadata).
 
 Installation
 ------------
@@ -195,42 +194,42 @@ Install without the ``sftp:`` or ``s3:`` backend::
 
 Install with the ``sftp:`` backend (more dependencies)::
 
-   pip install "borgstore[sftp]"
+    pip install "borgstore[sftp]"
 
 Install with the ``s3:`` backend (more dependencies)::
 
-   pip install "borgstore[s3]"
+    pip install "borgstore[s3]"
 
-Please note that ``rclone:`` also supports sftp or s3 remotes.
+Please note that ``rclone:`` also supports SFTP or S3 remotes.
 
 Want a demo?
 ------------
 
-Run this to get instructions how to run the demo:
+Run this to get instructions on how to run the demo::
 
-python3 -m borgstore
+    python3 -m borgstore
 
 State of this project
 ---------------------
 
 **API is still unstable and expected to change as development goes on.**
 
 **As long as the API is unstable, there will be no data migration tools,
-like e.g. for upgrading an existing store's data to a new release.**
+such as tools for upgrading an existing store's data to a new release.**
 
-There are tests and they succeed for the basic functionality, so some of the
-stuff is already working well.
+There are tests, and they pass for the basic functionality, so some of the
+functionality is already working well.
 
-There might be missing features or optimization potential, feedback is welcome!
+There might be missing features or optimization potential. Feedback is welcome!
 
-There are a lot of possible, but still missing backends. If you want to create
-and support one: pull requests are welcome.
+There are many possible backends that are still missing. If you want to create
+and support one, pull requests are welcome.
 
 Borg?
 -----
 
 Please note that this code is currently **not** used by the stable release of
-BorgBackup (aka "borg"), but only by borg2 beta 10+ and master branch.
+BorgBackup (also known as "borg"), but only by Borg 2 beta 10+ and the master branch.
 
 License
 -------

src/borgstore/__init__.py

@@ -1,5 +1,5 @@
 """
-BorgStore - a key/value store.
+BorgStore: a key/value store.
 """
 
 from ._version import __version__, version  # noqa