0
\$\begingroup\$

I have this public repository.

Since it's the first repository I have created, I'm looking for tips on what should I improve (mainly in the GH project structure), although tips in the code would be greatly appreciated as well.

ideally, I would like to be able to import this package via the pip install command.

pip install git+https://github.com/jtorre94/dummydf

(venv) C:\Users\u339990\my_python_project>pip install git+https://github.com/jtorre94/dummydf
Collecting git+https://github.com/jtorre94/dummydf
  Cloning https://github.com/jtorre94/dummydf to c:\users\myuser\appdata\local\temp\pip-req-build-0cywtbl6
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "C:\Users\myusers\AppData\Local\Continuum\anaconda3\lib\tokenize.py", line 447, in open
        buffer = _builtin_open(filename, 'rb')
    FileNotFoundError: [Errno 2] No such file or directory: 'C:\\Users\\u339990\\AppData\\Local\\Temp\\pip-req-build-0cywtbl6\\setup.py'
\$\endgroup\$
3
  • 1
    \$\begingroup\$ Welcome to Code Review! Unfortunately your question is off-topic as of now, as the code to be reviewed must be present in the question. Please add the code you want reviewed in your question. Thanks! \$\endgroup\$ Dec 22, 2021 at 13:22
  • \$\begingroup\$ Hi, @TobySpeight I understand that the code must be present in the question itself, but what I was asking for review was the package GH structure. How would that fit into the requirements? \$\endgroup\$
    – Javi Torre
    Dec 22, 2021 at 14:58
  • \$\begingroup\$ I'm not sure it is a good fit for CR, to be honest. I think we've had these file-layout questions before, and they have been closed as off-topic. Might be worth asking in Meta, or in Chat, if you want more guidance. \$\endgroup\$ Dec 22, 2021 at 15:55

1 Answer 1

0
\$\begingroup\$

Installing as a python package

To do this, you need to configure either a setup.py or setup.cfg file (or both). This defines all the requirements and settings that python should take into account when installing the package.

Documentation

You already have some documentation throughout the codebase which is great. However there are still some improvements possible.

Correct formatting of code samples

When documenting code samples, consider using >>> before every example. Apart from looking clearer (to someone who is used to the python standards), it also allows other tools to identify and parse that code.

Consider for example

  • doctest which can automatically test your code samples to make sure that your docs aren't lying.
  • Automated documentation, more on this in the next section.

Render documentation

You already have the documentation present, but for a new user it can be hard to delve through the code to find documentation. Therefore there are tools that can render your documentation in a cleaner website.

The most common one for python is sphinx. You can go very far with this, but it might be nice to test the quickstart in the linked tutorial.

You can provide this with github pages to provide free hosting of the docs.

One package that uses this method of documentation is requests. Consider for example the raw code for their main api versus the rendered documentation. Of course there is still a fair amount of text, but the extra highlighting, formatting and clickable links to other parts of the code are really helpfull for people new to your codebase.

\$\endgroup\$
6
  • \$\begingroup\$ Thanks a lot for your answer! If different libraries needed in dummydf and tests_dummydf, should the setup.cfg file be the same with all the dependencies or several setup files should be created? \$\endgroup\$
    – Javi Torre
    Dec 22, 2021 at 15:09
  • 1
    \$\begingroup\$ You can put the extra requirements for the tests under extras_require in the same setup.py file. You can do this for example using the name dev or test. Then a normal user can just install the package and use it (without the tests), while you can install it like pip install 'dummydf[dev]'. \$\endgroup\$ Dec 22, 2021 at 15:22
  • \$\begingroup\$ Thanks again! I know this is out of the initial scope of this question but: after uploading the setup.py file, I can import successfully dummydf via pip but somehow, the module is empty (does not include its main class DummyDataframe, for instance. Am I missing some config to tell pip that dummydf.py must be part of the module? \$\endgroup\$
    – Javi Torre
    Dec 22, 2021 at 15:35
  • 1
    \$\begingroup\$ It's hard to tell without the exact commands, but you might need to do from dummydf import dummydf to get the correct module (because both the root folder dummydf and dummydf.py are modules). There are some methods to resolve this if it annoys you, but they might be a bit out of scope for this answer. A good suggestions with these type of things is to look at existing packages and how they do it. \$\endgroup\$ Dec 22, 2021 at 15:43
  • 1
    \$\begingroup\$ This should offer some solutions. \$\endgroup\$ Dec 22, 2021 at 15:51

Not the answer you're looking for? Browse other questions tagged or ask your own question.