Closed lukasschwab closed 1 year ago
@mhils don't feel obligated to review my code, but my work here reminded me of your comments about project structure on https://github.com/lukasschwab/arxiv.py/pull/68.
This PR adds another module (arxiv.query
), which is reexported in __init__.py
alongside arxiv.arxiv
. If you're interested in weighing in, I'd appreciate your feedback; does this feel like an antipattern?
It looks like you want to publicly expose your entire API on the top-level arxiv
namespace, but you want to split up the code internally into different submodules ? In that case I personally would do what httpx does: Explicit imports + __all__
+ internal modules prefixed with an underscore.
https://github.com/encode/httpx/blob/master/httpx/__init__.py
There really is no super well-established convention here though, it boils down to personal preference a lot. I guess the only thing I would avoid is *
imports, it makes it hard for trace where things are actually coming from. For example when I'm interested in the definition of QuantitativeBiology
, __init__.py
currently has no hint on which submodule I need to look into. Does that make sense?
@mhils yes, that makes sense––thanks for the input!
It looks like you want to publicly expose your entire API on the top-level arxiv namespace, but you want to split up the code internally into different submodules?
Yeah, that's about right! With one complication: if possible, I want to avoid breaking the original import arxiv
usage.
If I were writing this package from scratch, I'd use named submodules:
arxiv.api
(the original module, currently named arxiv.arxiv
)arxiv.query
(unchanged)arxiv.fixtures
module for consts/enums defined by arXiv themselves. This is porbably a better name than arxiv.categories
... I'll think about renaming in this PR.The problem is that the current organization encourages import arxiv
, but also permits from arxiv import arxiv
.
I'm inclined to only allow explicit imports, but there are two issues:
import arxiv
usage is broken.arxiv.arxiv
to arxiv.api
to avoid from arxiv import arxiv
, but that's a breaking change.I suppose I could move the API logic into an arxiv.api
module; then––to avoid breaking changes––a deprected arxiv.arxiv
module can *
export arxiv.api
, and __init__.py
can auto-export arxiv.arxiv
.
Oh, looks like I jumped to conclusions! I can turn arxiv.query
and arxiv.arxiv
internal (arxiv._query
and arxiv._arxiv
respectively) and have init.py explicitly import certain values from them, like httpx
does.
I'll think more about this.
Closing: stale.
Description
Operator methods are capitalized because
def and()
anddef or()
are invalid Python: the tokens clash with Python's boolean operators. Considered_and
,_or
, but these have additional semantic meaning.Breaking changes
Expands, but doesn't break, the API.
query
module.category
module.Relevant issues
Fix #30
Checklist
README.md
example usage has been updated. Should think about whether to add examples; the README is a somewhat unwieldy way to manage documentation.