Skip to content

Commit ddc2bc7

Browse files
authored
Update guide.md
1 parent ae4e4bb commit ddc2bc7

File tree

1 file changed

+17
-5
lines changed

1 file changed

+17
-5
lines changed

docs/guide.md

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# 1. The way from [python-bugzilla](https://github.com/python-bugzilla/python-bugzilla)
22

3-
## 1.1 About *MI*
3+
## 1.1. About *MI*
44

5-
### 1.1.1 WHAT
5+
### 1.1.1. WHAT
66

77
**MI** stands for **Machine Interface**. The concept of MI originates from the well-known [GDB: The GNU Project Debugger](https://www.sourceware.org/gdb/) with docs at [GDB User Manual - The GDB/MI Interface](https://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_002fMI).
88

99
For this project, when you run **MI** from your terminal, it starts to wait until it reads a line from `stdin`, then performs the corresponding operation, and finally writes some results and necessary information to `stdout`. Of course, these corresponding operations may also include reading some strings from `stdin`, such as obtaining the user name and password during interactive login.
1010

11-
### 1.1.2 WHY
11+
### 1.1.2. WHY
1212

1313
[python-bugzilla](https://github.com/python-bugzilla/python-bugzilla) is undoubtedly an excellent project. It is packaged as a python library and published on [python-bugzilla - PyPI](https://pypi.org/project/python-bugzilla/). After running the installation scripts in `setup.py`, users could not only `import bugzilla` in their code, but also run `/usr/bin/bugzilla` directly in the terminal to use it through **CLI**.
1414

@@ -20,7 +20,7 @@ Not only that, we also hope that our new interface can **not only** be friendly
2020

2121
All the above reminds us of [GDB/MI Interface](https://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_002fMI). So we borrowed the concept of **MI** from here and developed what you see today: run `bugzilla-mi`, after seeing the prompt of *ArgumentParser waiting*, type just exactly the same parameters to `stdin` when running `bugzilla-cli`, then press Enter (actually a **line break** is typed in), and then continue to type something or just wait, and finally get the expected output in `stdout`. After that you will continue to see the prompt of *ArgumentParser waiting*, and then get into another new round of typing parameters.
2222

23-
### 1.1.3 HOW
23+
### 1.1.3. HOW
2424

2525
It is easy to find that after installation running `/usr/bin/bugzilla` in terminal is exactly equivalent to running `python ./bugzilla-cli` in the project root directory of [python-bugzilla](https://github.com/python-bugzilla/python-bugzilla). And `bugzilla-cli` is actually just a wrapper of `_cli.main`. So we do the surgery on a copy of `_cli.py`, i.e., `_mi.py`. Although original `_cli.py` looks complex, it is highly cohesive and low coupling, so the surgery is easy. We
2626

@@ -31,6 +31,18 @@ It is easy to find that after installation running `/usr/bin/bugzilla` in termin
3131
* add a cache mechanism in `_make_bz_instance` to make a new instance when necessary;
3232
* add many `try-except` and `raise` statements to make the round by round loop process run robustly without unexpected interruption.
3333

34+
## 1.2. Something shrunk
3435

36+
You can see that although generally we are adding sth rather than deleting, many files have been deleted compared with the original content. We will briefly explain this below to help you understand the purpose of doing so.
3537

36-
## 1.2 Something shrunk
38+
### 1.2.1. setup files
39+
40+
The main purpose we expect is to serve as a backend of some automation control systems. In this case, we believe that installing into *site-packages* of your Python environment may be a bad choice. We expect the users to be **free to choose and control** where to place and run these scripts without the help of `pip`. Therefore, it is sufficient to provide only `bugzilla-cli` for forward compatibility and `bugzilla-mi` for daily use. If you want to import from *site-packages*, or just type `bugzilla --balabala` in your terminal and press Enter anyway, you are recommended to select the original [python-bugzilla](https://github.com/python-bugzilla/python-bugzilla).
41+
42+
### 1.2.2. tests, quality-checks and docs
43+
44+
Limited by our time and resources, these less important content has been removed. And our development does not involve changing the original code in package `bugzilla`, we only add something new. What we need to confirm is that once there is no problem in original *python-bugzilla*, the code added by us will also work well. Therefore, only things related to the newly added code are retained.
45+
46+
47+
48+
# 2. Usage

0 commit comments

Comments
 (0)