Control: reopen -1 Control: tags -1 + patch Hi Stuart,
On Sun, Sep 10, 2017 at 01:47:22AM +1000, Stuart Prescott wrote: > That iter_paragraphs works with compressed indexes at all is somewhat > accidental. I don't believe it is documented anywhere that this is a > supported > use of iter_paragraphs. (But it's rather handy that it does work!) In fact, > the documentation says that iter_paragraphs accepts: > > sequence: a string, or any any object that returns a line of > input each time, normally a file. > > (not a compressed file). > > Further, my feeling is that if a user chooses to break a Recommends, they get > what is coming to them and policy is quite clear about that. Thanks for your explanation, I agree with your conclusions. > As a user of the iter_paragraphs (and other!) functions, if you are in a > position to add to the docstrings of these functions so that this contract is > more clear to programmer, then that would be greatly appreciated. Building > some API docs with sphinx is something we should aim for but at present, > there > is not nearly enough documentation to make that worthwhile. I attached a patch that adds a couple lines of doc. In the process I realised there was a deprecated example with shared_storage in a README, which I took the opportunity to remove. Cheers, -- Matthieu
From 86df0a5b86ec44f07e4fa624d33a5a002a479359 Mon Sep 17 00:00:00 2001
From: Matthieu Caneill <m...@brokenwa.re>
Date: Fri, 6 Oct 2017 21:47:35 +0200
Subject: [PATCH] deb822: add clarifications for iter_paragraphs with
compressed files
---
README.deb822 | 6 ++----
lib/debian/deb822.py | 4 +++-
2 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/README.deb822 b/README.deb822
index 89e7d64..4480c87 100644
--- a/README.deb822
+++ b/README.deb822
@@ -68,10 +68,8 @@ For example:
print src['Package'], src['Version']
This method uses python-apt if available to parse the file, since it
-significantly boosts performance. The downside, though, is that yielded
-objects share storage, so they should never be kept accross iterations.
-To prevent this behavior, pass a "shared_storage=False" keyword-argument
-to the iter_paragraphs() function.
+significantly boosts performance. If python-apt is not present and the
+file is a compressed file, it must first be decompressed manually.
Sample usage (TODO: Improve)
diff --git a/lib/debian/deb822.py b/lib/debian/deb822.py
index 26f4b68..84af3c2 100644
--- a/lib/debian/deb822.py
+++ b/lib/debian/deb822.py
@@ -313,7 +313,9 @@ class Deb822(Deb822Dict):
:param sequence: a string, or any any object that returns a line of
input each time, normally a file. Alternately, sequence can
- be a dict that contains the initial key-value pairs.
+ be a dict that contains the initial key-value pairs. When
+ python-apt is present, sequence can also be a compressed object,
+ for example a file object associated to something.gz.
:param fields: if given, it is interpreted as a list of fields that
should be parsed (the rest will be discarded).
--
2.8.1
signature.asc
Description: PGP signature
