[python3-ldap] Feedback on aspects of python3-ldap's API

[Will Yardley]

> Anyway there are some convenience functions in the
> ldap3.extend.standard namespace that act as you intend. In the case of
>  "paged" searches you can get the result back directly in the search
> operation that act as a generator (or an accumulator). For example you
> can have:
> 
> # simple paged search with generator - useful when returning a big dataset
> for response in self.connection.extend.standard.paged_search('o=test',
> '(cn=*)'):
>             do_whatever_with(response)

This seems much easier than, and preferable to, the first example in
your documentation, which looks similar to the example for dealing with
paged results in python-ldap.

However, given how common search result limits are with the default
configs of modern LDAP implementations, both AD and other systems like
389, I wonder if it wouldn't be easier (from the standpoint of
end-users) to just have an option to the connection and / or the query
that lets you set the # of max results per query, i.e.,, why not just
let the user specify 'paged_size=1000' and let the code handle how to
deal with that in a less exposed way. If it's set for the connection,
the limit would apply to all searches, and if it's set for the search,
it would apply to that search. That way, instead of having to call,
e.g.,

connection.extend.standard.paged_search('o=test', '(cn=*)', paged_size=1000)
you can just call
search('o=test', '(cn=*)', paged_size=1000)

and then have the results presented in a data structure in the same way
an unpaged search would be.

I do think that feedback from people with more distance from the module,
both ordinary users and developers of other modules, might be handy.
While python-ldap has a lot of flaws IMHO, and I've long been surprised
at some of the things it can't do natively, if something's going to
replace it, I'd love to see it be something that is easy to use as well
as powerful -- the ease of use and consistency of modules is one of the
things that I think makes Python strong. And, while there might be some
pain in changing interfaces or maintaining backwards compatibility now,
it's nothing compared to what it will be once the project is more widely
used.

To me, imaplib and smtplib (while they do somewhat different types of
things) are great examples of modules that are powerful, flexible, but
also very easy to use for simple use-cases, and have a very logical
interface. Someone with fairly little understanding of the protocol can
configure them to receive / send mail with just a few configuration
options (see,
https://docs.python.org/2/library/imaplib.html#imap4-example). But in
cases where you need to directly access a particular method to, for
example, start a session and send RCPT TO, without actually sending a
message, it's also very easy to deal with.

And, as I've mentioned before, I think figuring out some more abstract
way to represent search filters would be really great, though I will
admit to not knowing exactly how such a layer would look. I don't find
the current one very logical personally, and from what I understand,
there are a few types of combinations that can't be represented using
it.

w