r/learnpython • • Aug 25 '20

How to read/understand a git repository?

I'm trying to learn how to make a python programs by looking through existing programs in a similar premise as what I'd like to achieve (learning by looking at examples). But one thing I'm having difficulty with is finding out how these github repos are organized.

So far (in the repo I have I'm viewing) I know that bin usually means terminal/command-line commands, docs is typically documentation (as one might expect), test is self explanatory, but some things I don't know is rpm and stubs, amongst others.

Is there a resource to learn how python/git programs are organized? And what to expect when looking through repos?

334 Upvotes

13 comments sorted by

62

u/Codes_with_roh Aug 25 '20 edited Aug 25 '20

stubs basically means:

A small software routine placed into a program that provides a common function. Stubs are used for a variety of purposes. For example, a stub might be installed in a client machine, and a counterpart installed in a server, where both are required to resolve some protocol, remote procedure call (RPC) or other interoperability requirement.

rpm means:

The RPM Package Manager (RPM) is a package management system that runs on Red Hat Enterprise Linux, CentOS, and Fedora. RPM makes it easier for you to distribute, manage, and update software that you create for Red Hat Enterprise Linux, CentOS, and Fedora. Many software vendors distribute their software via a conventional archive file (such as a tarball)

This blog will provide you the information about organizing your repos.

While going through the repo the most important thing to keep in mind is to read and understand the .readme throughly because a well maintained repo contains all the information of usage inside the .readme.

25

u/[deleted] Aug 25 '20

This isn't really how "stubs" is used in practice...

In practice, "stubs" means "a replacement for the real thing". Something that someone else needs to write based on the given example. Eg. you may have a template for implementing context managers, that looks like this:

class $1:
    def __init__(self):
        # A stub for constructor
        pass
    def __enter__(self):
        # A stub for with ... as x:
        pass
    def __exit__(self, v, t, b):
        # A stub for exception handling
        pass

Wiki gives a better description ( https://en.wikipedia.org/wiki/Method_stub )

A method stub or simply stub[1] in software development is a piece of code used to stand in for some other programming functionality. A stub may simulate the behavior of existing code (such as a procedure on a remote machine, such methods are often called mocks) or be a temporary substitute for yet-to-be-developed code. Stubs are therefore most useful in porting, distributed computing as well as general software development and testing.

19

u/DrMaxwellEdison Django and stuff Aug 25 '20

Great question, and the answer really depends on how the maintainer(s) of that code choose to organize, as there aren't really standards to follow.

What I find is that most often a repo will contain:

  1. The source code in a directory named src or a similar name as the package itself (in the case of your example, libqstile looks right); and

  2. Everything else. Docs, tests, binaries (that's the bin part, by the way), license, notes on how to contribute, CI workflow configurations, etc.

When you're interested in how the code works, put #2 to the side, and focus on #1. Dive into that source folder and get cracking. Often a good place to start is the root __init__.py file, which can give clues as to how different objects are made importable from the top level of the package.

5

u/_________KB_________ Aug 25 '20

The 'bin' directory stands for binaries and is usually the place where any compiled or built binaries are placed, or other scripts that are the main executable files for the project. Quite often a github repository won't have a bin folder because they expect you to build the project yourself from the source code, or the project could be written in an interpreted language like Python that doesn't really have built binaries.

19

u/dermotmcg Aug 25 '20

Great question

4

u/kramrm Aug 25 '20 edited Aug 25 '20

There isn’t one “right” way to organize a repo. (Though there are wrong ways). It also depends on the language(s) used. I don’t usually have a bin in my Python repos. For those, I generally have project info in the root folder and all the actual code inside src.

2

u/Decency Aug 25 '20

One rule of git repos is that they should contain only human readable things. So if you have a bin directory, pretty much by definition you're doing it wrong.

3

u/kramrm Aug 25 '20

It’s one thing to include a library file your code may need (though not as common with Python as other languages), but a compiled version of your project should be in release assets, not the repo itself.

2

u/[deleted] Aug 25 '20

They don't seem to have included any build/install instructions. There's a comment in the Makefile which reads:

This is a little ugly: we want to be able to have users just run# 'python setup.py install' to install qtile

So I guess try that? As root, run 'python setup.py install' (or python3 setup.py install if your python isn't a python3)

3

u/Sigg3net Aug 25 '20

test is self explanatory

Yes, it is I who is dumb.

1

u/b_ootay_ful Aug 25 '20

The best thing I learnt from github is if it's a program, add /releases at the end of the url to find the downloadable program.

0

u/[deleted] Aug 25 '20

but some things I don't know is rpm and stubs, amongst others.

I'd google rpm spec and mypy stubs.