Skip to content

Accept language wip #335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 99 commits into from
Aug 28, 2017
Merged

Accept language wip #335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
99 commits
Select commit Hold shift + click to select a range
b62746a
Add AcceptLanguageValidHeader class with .__init__ and .parse().
whiteroses Jul 6, 2017
085d847
Document instance attributes of AcceptLanguageValidHeader.
whiteroses Jul 6, 2017
0298dfc
Add AcceptLanguageValidHeader.basic_filtering().
whiteroses Jul 7, 2017
f3faed0
Fix comment.
whiteroses Jul 7, 2017
3acd533
Improve docstring.
whiteroses Jul 7, 2017
a35a98b
Make comment more precise.
whiteroses Jul 8, 2017
1e17ac3
Replace loop with any() and a generator.
whiteroses Jul 8, 2017
c402919
Add AcceptLanguageValidHeader.lookup().
whiteroses Jul 11, 2017
2d7619d
Add AcceptLanguage._old_match.
whiteroses Jul 13, 2017
7d50f17
Add AcceptLanguageValidHeader.__iter__.
whiteroses Jul 13, 2017
ba91ba7
Add AcceptLanguageValidHeader.__contains__.
whiteroses Jul 13, 2017
aae932f
Improve comment.
whiteroses Jul 14, 2017
8d6a4a9
Fix typo.
whiteroses Jul 15, 2017
0c6df1a
Add AcceptLanguageValidHeader.best_match.
whiteroses Jul 15, 2017
d18f69a
Minor rewording in docstring.
whiteroses Jul 16, 2017
3afb478
Add AcceptLanguageValidHeader.quality().
whiteroses Jul 16, 2017
aa94a27
Add colon.
whiteroses Jul 16, 2017
cc422c7
Make heading bold.
whiteroses Jul 16, 2017
59b8b75
Improve docstring.
whiteroses Jul 16, 2017
e9679b9
Add deprecation warnings.
whiteroses Jul 16, 2017
218b1d1
Add _AcceptLanguageInvalidOrNoHeader class.
whiteroses Jul 16, 2017
5c849e8
Add _AcceptLanguageInvalidOrNoHeader.__contains__ and test.
whiteroses Jul 16, 2017
decbb08
Fix docstring.
whiteroses Jul 16, 2017
71b8f95
Add _AcceptLanguageInvalidOrNoHeader.__iter__.
whiteroses Jul 16, 2017
d33edf3
Add _AcceptLanguageInvalidOrNoHeader.__nonzero__.
whiteroses Jul 16, 2017
5c4762b
Add AcceptLanguageValidHeader.__nonzero__/.__bool__ and test.
whiteroses Jul 16, 2017
db2b411
Add _AcceptLanguageInvalidOrNoHeader.basic_filtering.
whiteroses Jul 16, 2017
5e9a364
Add missing space.
whiteroses Jul 16, 2017
660aef9
Add _AcceptLanguageInvalidOrNoHeader.best_match.
whiteroses Jul 17, 2017
2e35a87
Remove call to _check_offer().
whiteroses Jul 17, 2017
7cdf90e
Add _AcceptLanguageInvalidOrNoHeader.quality.
whiteroses Jul 17, 2017
df056c4
Add _AcceptLanguageInvalidOrNoHeader.lookup and tests.
whiteroses Jul 17, 2017
0145b79
Add AcceptLanguageNoHeader class, __init__, test and documentation.
whiteroses Jul 17, 2017
8f459bf
Add AcceptLanguageInvalidHeader class, __init__, test and doc.
whiteroses Jul 17, 2017
10a89f2
Add __repr__ and tests for the three AcceptLanguage classes.
whiteroses Jul 18, 2017
009374d
Add __str__ and tests for the three AcceptLanguage classes.
whiteroses Jul 18, 2017
5247679
Add create_accept_language_header().
whiteroses Jul 22, 2017
115cee2
Turn re-usable code into function.
whiteroses Jul 22, 2017
1fa105d
Add __add__ and __radd__ for AcceptLanguageValidHeader, with tests.
whiteroses Jul 22, 2017
a49b1b2
Add __add__ and __radd__ for AcceptLanguageNoHeader, with tests.
whiteroses Jul 22, 2017
9f59da5
Add __add__ and __radd__ for AcceptLanguageInvalidHeader, with tests.
whiteroses Jul 22, 2017
d52159f
Add blank line.
whiteroses Jul 22, 2017
3b23a87
Add docstrings for NoHeader's and InvalidHeader's __str__s.
whiteroses Jul 22, 2017
3ca3602
Update documentation.
whiteroses Jul 22, 2017
c9d132b
Test NoHeader and InvalidHeader rather than InvalidOrNoHeader.
whiteroses Jul 22, 2017
d558edf
Add accept_language_property and tests.
whiteroses Jul 23, 2017
2febfa1
Use accept_language_property in request.
whiteroses Jul 23, 2017
5292e2e
Update AcceptLanguage class, and stop inheriting from Accept.
whiteroses Jul 23, 2017
ad9c288
Remove HeaderClass attribute, which we no longer need.
whiteroses Jul 23, 2017
e73ea05
Make test methods' names and order consistent.
whiteroses Jul 23, 2017
ca4e613
Assert that all three subclasses are instances of AcceptLanguage.
whiteroses Jul 23, 2017
3b1fbcb
Add a blank line after docstrings documenting classes.
whiteroses Jul 23, 2017
09c12ed
Remove :inherited-members: option.
whiteroses Jul 23, 2017
8b9a39a
Make docstring a raw string.
whiteroses Jul 23, 2017
3cae8fe
Add deprecation warnings for __iter__.
whiteroses Jul 23, 2017
2074517
Fix wording.
whiteroses Jul 23, 2017
84a8fd7
Add tests for AcceptLanguageValidHeader.best_match.
whiteroses Jul 24, 2017
531e63e
Add tests for ...NoHeader.best_match and ...InvalidHeader.best_match.
whiteroses Jul 24, 2017
569d1a4
Add tests for .quality().
whiteroses Jul 24, 2017
38f8a8d
Remove check for 'q'.
whiteroses Jul 24, 2017
0a5cd70
Add tests for Accept.__iter__ and NilAccept.__iter__.
whiteroses Jul 24, 2017
b69ceab
Remove :members: option.
whiteroses Jul 24, 2017
949ceb4
Make .header_value and .parsed read-only properties.
whiteroses Jul 25, 2017
47809be
Set autodoc_member_order.
whiteroses Jul 25, 2017
0e69548
Change variable name from ``accept_language`` to ``instance``.
whiteroses Jul 25, 2017
a47db23
Make AcceptLanguageInvalidHeader.__repr__ safer.
whiteroses Jul 25, 2017
7622489
Make AcceptLanguageValidHeader.__repr__ safer.
whiteroses Jul 25, 2017
1c6dbaf
Make __repr__ consistent between the AcceptLanguage classes.
whiteroses Jul 25, 2017
f591272
Stop displaying header_value in AcceptLanguageValidHeader.__repr__.
whiteroses Jul 25, 2017
1bf58d9
Improve comment.
whiteroses Jul 25, 2017
faab81b
Change double quotes to single quotes for consistency.
whiteroses Jul 25, 2017
ecf671f
Remove comment.
whiteroses Jul 25, 2017
0967b02
Remove unnecessary blank lines.
whiteroses Jul 26, 2017
1de163f
Improve __repr__ of AcceptLanguage classes.
whiteroses Jul 29, 2017
ccc02e8
Add functions to help with forming the regexes for parsing the headers.
whiteroses Jul 29, 2017
e9e911c
Remove note on parsing.
whiteroses Aug 1, 2017
2998875
Remove unnecessary ``else:``.
whiteroses Aug 1, 2017
c825cc1
Change 'generator' to 'generator iterator' to avoid ambiguity.
whiteroses Aug 1, 2017
7866f75
Use more helpful variable names.
whiteroses Aug 1, 2017
eceb488
Raise ValueError with error message.
whiteroses Aug 1, 2017
8abc5aa
Change 'generator iterator' to 'iterator' in docstring.
whiteroses Aug 1, 2017
f003cd8
Change test imports to module scope.
whiteroses Aug 2, 2017
82df771
Add spaces.
whiteroses Aug 2, 2017
2f293c7
Treat invalid header values like ``NoHeader``s when __add__ing.
whiteroses Aug 10, 2017
55d3233
Remove unused `default_quality` parameter.
whiteroses Aug 10, 2017
54bcba3
Fix missing commas and spacing in single-element tuples.
whiteroses Aug 21, 2017
9e04492
Correct and improve wording of docstrings.
whiteroses Aug 21, 2017
eaf0d5b
Improve wording in docstring.
whiteroses Aug 22, 2017
259b497
Simplify regexes.
whiteroses Aug 22, 2017
ea3e9ef
Add underscore to classmethod to make it clear that it's not public API.
whiteroses Aug 23, 2017
7470666
Change PendingDeprecationWarnings to DeprecationWarnings.
whiteroses Aug 23, 2017
c2c3bdf
Check and raise instead of using asserts.
whiteroses Aug 23, 2017
6d7ffe8
Remove undocumented `modifier` parameter.
whiteroses Aug 23, 2017
f365864
Remove unnecessary blank line.
whiteroses Aug 24, 2017
e884501
Move .parse from AcceptLanguageValidHeader to AcceptLanguage.
whiteroses Aug 24, 2017
20bb604
Update to say AcceptLanguageValidHeader._old_match will be deprecated.
whiteroses Aug 25, 2017
218a7f2
Fix typo.
whiteroses Aug 25, 2017
a11a6ed
Add missing word.
whiteroses Aug 28, 2017
1916764
Fix incorrect test.
whiteroses Aug 28, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions docs/api/webob.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,25 @@ Accept-*
:members:
:inherited-members:

.. autofunction:: create_accept_language_header

.. autoclass:: AcceptLanguage
:members:
:inherited-members:
:members: parse

.. autoclass:: AcceptLanguageValidHeader
:members: header_value, parsed, __init__, __add__, __contains__, __iter__,
__radd__, __str__, parse, basic_filtering, best_match, lookup,
quality

.. autoclass:: AcceptLanguageNoHeader
:members: header_value, parsed, __init__, __add__, __contains__, __iter__,
__radd__, __str__, parse, basic_filtering, best_match, lookup,
quality

.. autoclass:: AcceptLanguageInvalidHeader
:members: header_value, parsed, __init__, __add__, __contains__, __iter__,
__radd__, __str__, parse, basic_filtering, best_match, lookup,
quality
Copy link
Member

@mmerickel mmerickel Aug 28, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we remove the subclasses from the public api now?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can if we combine the docstrings for all the subclasses for each method and put them all into AcceptLanguage. This would imo make some already complicated docstrings even more complicated, adding another layer to the branching. And as I mentioned before, the instances would still i.d. as the subclasses (I guess we could change the __repr__ to indicate that it is a subclass of AcceptLanguage, so people would know to look there?) If you want me to go ahead and make the change, I will — it's not trivial, and will take some time and thought on how to combine the docstrings from the three subclasses for each method. (I would also have to do the same for the other three headers.)

Would it be possible to merge this so I can push changes for this and the other three headers before the deadline tomorrow to a more appropriately-named PR, or should I push the changes for all four headers to this one?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's fine if we want to merge this now. I'm happy with that.

Part of the idea of making the subclasses "hidden" is not that people don't know about them but that they don't care. I'm more worried about the docs the user sees than the actual objects they see in the repl. With that in mind we'd want to make the docstrings focus on valid headers with just a sentence or two in each that explains what happens with invalid/missing data. I can't imagine that will make the docstrings that much more complex or harder to parse but I could be wrong!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was worrying whether it would be clear enough that people should look at the docs for AcceptLanguage if the objects identify as the subclasses, but I understand what you are looking for, and will try to combine the docstrings and document one api under the base class after I've finished wrapping up the four headers and all the necessary submissions for gsoc. Could you please merge this PR if everything is ok, so I can open a new PR and push the other changes? (Sorry about the last-minute commits, they are minor changes to fix small mistakes.) Thanks!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again @whiteroses I'm happy with all of this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright, any future work can be done in a different PR.


.. autoclass:: MIMEAccept
:members:
Expand Down
2 changes: 2 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@

modindex_common_prefix = ['webob.']

autodoc_member_order = 'bysource'

# -- Options for HTML output ---------------------------------------------

html_theme = 'alabaster'
Expand Down
Loading