BufferingHandler's documentatio says "Initializes the handler with a buffer of the specified capacity." but it does not specify what capacity means. One would assume the intention is to give a bound to memory usage, and that capacity is bytes.

Looking at the source instead, the check is:

        return (len(self.buffer) >= self.capacity)

and self.buffer is initialised with an empty list, so capacity is a number of lines, which cannot be used to constrain memory usage, and for which I struggle to see a use case.

I believe that the current behaviour is counterintuitive enough to deserve, if not changing, at least documenting

Python isn't a low-level language, and there isn't *in general* a particular intention "to give a bound to memory usage". When using "buffer" in a general sense, rather than a buffer object (which is more akin to a byte-array), it's usually understood to mean a Python list (used as an array) and the capacity refers to the number of elements.

You may struggle to see a use case for specifying a buffer capacity as a number of elements rather than a byte size, but that doesn't mean that such use cases don't exist.

Are you perhaps using MicroPython in a constrained-memory environment?

In the 17 years that this code has been in Python, it's the first time AFAIK that anyone has raised the term "capacity" as potentially confusing, so I don't think such confusion is common. However, I'll be happy to update the documentation to clarify that "capacity" means "number of records buffered".

Thanks! Clarifying "number of records buffered" would perfectly solve the problem for me.

New changeset 84de34e39eb9e49b2ae691c6f67df8d7da3561de by Vinay Sajip in branch 'master':
bpo-32934: Clarified meaning of 'capacity' for BufferingHandler and MemoryHandler. (GH-14498)
https://github.com/python/cpython/commit/84de34e39eb9e49b2ae691c6f67df8d7da3561de

New changeset 471d785dc759eb2e9c06f077f323cf136d32506b by Vinay Sajip (Miss Islington (bot)) in branch '3.7':
bpo-32934: Clarified meaning of 'capacity' for BufferingHandler and MemoryHandler. (GH-14498) (GH-14508)
https://github.com/python/cpython/commit/471d785dc759eb2e9c06f077f323cf136d32506b

New changeset 3db5c5c7630af92336a8c0a269e05607cd68f9e7 by Vinay Sajip (Miss Islington (bot)) in branch '3.8':
bpo-32934: Clarified meaning of 'capacity' for BufferingHandler and MemoryHandler. (GH-14498) (GH-14507)
https://github.com/python/cpython/commit/3db5c5c7630af92336a8c0a269e05607cd68f9e7