Skip to content

Commit bca4b4e

Browse files
avara1986avara1986
authored
Merge pull request #58 from python-microservices/task/updated-documentation
Updated docs
2 parents 2f4a836 + 296930f commit bca4b4e

File tree

9 files changed

+259
-51
lines changed

9 files changed

+259
-51
lines changed

‎README.md‎

Lines changed: 39 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -39,26 +39,51 @@ Nowadays, is not perfect and we have a looong roadmap, but we hope this library
3939
pip install py-ms
4040
```
4141

42-
## Structure
42+
# Quickstart
4343

44-
### pyms/config
45-
Module to read yaml or json configuration from a dictionary or a path.
44+
You need to create 2 files: main.py and config.yml:
4645

47-
### pyms/flask/app
48-
With the function `create_app` initialize the Flask app, register [blueprints](http://flask.pocoo.org/docs/0.12/blueprints/)
49-
and initialize all libraries such as Swagger, database, trace system, custom logger format, etc.
46+
main.py
47+
```python
48+
from flask import jsonify
5049

51-
### pyms/flask/services
52-
Integrations and wrappers over common libs like request, swagger, connexion
50+
from pyms.flask.app import Microservice
5351

54-
### pyms/flask/healthcheck
55-
This view is usually used by Kubernetes, Eureka and other systems to check if our application is running.
52+
ms = Microservice(path=__file__) # 1.1
53+
app = ms.create_app() # 2.1
5654

57-
### pyms/logger
58-
Print logger in JSON format to send to server like Elasticsearch. Inject span traces in logger.
5955

60-
### pyms/tracer
61-
Create an injector `flask_opentracing.FlaskTracer` to use in our projects.
56+
@app.route("/") # 3.1
57+
def example():
58+
return jsonify({"main": "hello world"})
59+
60+
61+
if __name__ == '__main__':
62+
app.run()
63+
```
64+
65+
config.yml
66+
```yaml
67+
pyms: # 1.2
68+
requests:
69+
data: {}
70+
ms: # 1.3
71+
DEBUG: true
72+
APP_NAME: business-glossary
73+
APPLICATION_ROOT : ""
74+
SECRET_KEY: "gjr39dkjn344_!67#"
75+
```
76+
77+
### So what did that code do?
78+
79+
1. Create a instance of PyMS Microservice class (#1.1). This initialization inject the configuration defined in the
80+
1.3 block and could be accessed through current_app.config. Then, initialize the service defined in the 1.2 block. See [Services](services.md) for more details.
81+
2. Initialize [Flask](https://flask.palletsprojects.com/en/1.1.x/) instance, [Connexion](https://github.com/zalando/connexion)
82+
if it was defined in the pyms configuration block, create a tracer, add health-check blueprint, initialize libs and set the PyMS Microservice in
83+
`ms` attribute and you can access to it with `current_app.ms`. This steps has their each functions and you can easy override it.
84+
3. `create_app` return the flask instance and you can interact with it as a typical flask app
85+
86+
See Documentation https://py-ms.readthedocs.io/en/latest/ to learn more.
6287

6388
## How To Contrib
6489
We appreciate opening issues and pull requests to make PyMS even more stable & useful! See [This doc](COONTRIBUTING.md)

‎docs/configuration.md‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# Configuration
22

3+
## Environments variables of PyMS:
4+
5+
**CONFIGMAP_FILE**: The path to the configuration file. By default, PyMS search the configuration file in your
6+
actual folder with the name "config.yml"
7+
**CONFIGMAP_SERVICE**: the name of the keyword that define the block of key-value of [Flask Configuration Handling](http://flask.pocoo.org/docs/1.0/config/)
8+
and your own configuration (see the next section to more info)
9+
310
## Create configuration
411
Each microservice needs a config file in yaml or json format to work with it. This configuration contains
512
the Flask settings of your project and the [Services](services.md). With this way to create configuration files, we
@@ -44,7 +51,6 @@ or in a config.json:
4451

4552
This file could contains this keywords:
4653

47-
4854
## pyms block
4955

5056
```pyms```: all subsets inside this keyword are the settings of this library. Each keyword will be a service of our
@@ -96,6 +102,8 @@ ms1-api:
96102
TESTING: false
97103
```
98104

105+
You can set this keyword with the environment var **CONFIGMAP_SERVICE**.
106+
99107
## Import Configuration
100108
With pyms, all configuration is stored as flask configuration and it can be acceded from:
101109

@@ -142,4 +150,37 @@ API = Api(
142150
```
143151

144152
**IMPORTANT:** If you use this method to get configuration out of context, you must set the `CONFIGMAP_SERVICE` or set
145-
the default key `ms` for your configuration block in your config.yml
153+
the default key `ms` for your configuration block in your config.yml
154+
155+
156+
## Looking for Configuration file with Kubernetes Configmaps
157+
By default, Microservice class search a config.yml in the same path. You can set a different route or set a json file.
158+
To change this path, define a environment variable `CONFIGMAP_FILE`.
159+
160+
This way of looking for the configuration is useful when you work with Docker and Kubernetes. For example, you can integrate
161+
a configmap of Kubernetes, with this microservice and a deployment with:
162+
163+
```yaml
164+
apiVersion: extensions/v1beta1
165+
kind: Deployment
166+
metadata:
167+
name: my-microservice
168+
spec:
169+
replicas: 1
170+
template:
171+
spec:
172+
containers:
173+
- name: my-microservice
174+
image: ...
175+
env:
176+
- name: CONFIGMAP_FILE
177+
value: "/usr/share/microservice/config.yaml"
178+
179+
volumeMounts:
180+
- mountPath: /usr/share/microservice
181+
name: ms-config-volume
182+
volumes:
183+
- name: ms-config-volume
184+
configMap:
185+
name: my-microservice-configmap
186+
```

‎docs/index.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
11
# Welcome to PyMS
22

3-
PyMS, Python MicroService, is a collection of libraries, best practices and recommended ways to build
4-
microservices with Python.
3+
PyMS, Python MicroService, is a [Microservice chassis pattern](https://microservices.io/patterns/microservice-chassis.html)
4+
like Spring Boot (Java) or Gizmo (Golang). PyMS is a collection of libraries, best practices and recommended ways to build
5+
microservices with Python which handles cross-cutting concerns:
6+
- Externalized configuration
7+
- Logging
8+
- Health checks
9+
- Metrics (TODO)
10+
- Distributed tracing
11+
12+
PyMS is powered by [Flask](https://flask.palletsprojects.com/en/1.1.x/), [Connexion](https://github.com/zalando/connexion) and [Opentracing](https://opentracing.io/).
13+
14+
Get started with [Installation](installation.md) and then get an overview with the [Quickstart](quickstart.md).
515

616
## Motivation
717

@@ -24,9 +34,11 @@ Nowadays, is not perfect and we have a looong roadmap, but we hope this library
2434

2535

2636
## Index:
27-
* [PyMS structure](structure.md)
37+
* [Installation](installation.md)
38+
* [Quickstart](quickstart.md)
2839
* [Configuration](configuration.md)
2940
* [Services](services.md)
41+
* [PyMS structure](structure.md)
3042
* [Microservice class](ms_class.md)
3143
* [Quick start and examples](examples.md)
3244
* [Structure of a microservice project](structure_project.md)

‎docs/installation.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Installation
2+
3+
## Python Version
4+
We recommend using the latest version of Python 3. PyMS supports Python 3.6 and newer and PyPy.
5+
6+
```
7+
virtualenv --python=python[3.6|3.7|3.8] venv
8+
source venv/bin/activate
9+
```
10+
11+
## Install PyMS
12+
13+
```
14+
pip install py-ms
15+
```
16+
17+
See [Quickstart](quickstart.md) to continue with this tutorial

‎docs/ms_class.md‎

Lines changed: 79 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -58,38 +58,89 @@ print(ms.config.multiplevars.config2)
5858
# >> "test2"
5959
```
6060

61+
## Personalize your microservices
6162

63+
Microservice class initialize the libraries and other process by this way:
6264

63-
# Looking for Configuration file
64-
By default, Microservice class search a config.yml in the same path. You can set a different route or set a json file.
65-
To change this path, define a environment variable `CONFIGMAP_FILE`.
65+
```python
66+
...
67+
def create_app(self):
68+
"""Initialize the Flask app, register blueprints and initialize
69+
all libraries like Swagger, database,
70+
the trace system...
71+
return the app and the database objects.
72+
:return:
73+
"""
74+
self.application = self.init_app()
75+
self.application.config.from_object(self.config)
76+
self.application.tracer = None
77+
self.application.ms = self
78+
79+
# Initialize Blueprints
80+
self.application.register_blueprint(healthcheck_blueprint)
81+
82+
self.init_libs()
83+
self.add_error_handlers()
84+
85+
self.init_tracer()
86+
87+
self.init_logger()
88+
89+
return self.application
90+
```
6691

67-
This way of looking for the configuration is useful when you work with Docker and Kubernetes. For example, you can integrate
68-
a configmap of Kubernetes, with this microservice and a deployment with:
92+
Create a class that innerit from `pyms.flask.app.Microservice` and create and override methods with your own configuration.
93+
The next example show how to create your own logger and innit a lib like [Flask Babel](https://pythonhosted.org/Flask-Babel/)
6994

70-
```yaml
71-
apiVersion: extensions/v1beta1
72-
kind: Deployment
73-
metadata:
74-
name: my-microservice
75-
spec:
76-
replicas: 1
77-
template:
78-
spec:
79-
containers:
80-
- name: my-microservice
81-
image: ...
82-
env:
83-
- name: CONFIGMAP_FILE
84-
value: "/usr/share/microservice/config.yaml"
85-
86-
volumeMounts:
87-
- mountPath: /usr/share/microservice
88-
name: ms-config-volume
89-
volumes:
90-
- name: ms-config-volume
91-
configMap:
92-
name: my-microservice-configmap
95+
```python
96+
class MyMicroservice(Microservice):
97+
def init_tracer(self):
98+
pass # Disabled tracer
99+
100+
def init_libs(self):
101+
babel = Babel(self.application)
102+
103+
return self.application
104+
105+
def init_logger(self):
106+
level = "INFO"
107+
LOGGING = {
108+
'version': 1,
109+
'disable_existing_loggers': False,
110+
'formatters': {
111+
'console': {
112+
'format': '[%(asctime)s][%(levelname)s] %(name)s '
113+
'%(filename)s:%(funcName)s:%(lineno)d | %(message)s',
114+
'datefmt': '%H:%M:%S',
115+
},
116+
},
117+
'handlers': {
118+
'console': {
119+
'level': level,
120+
'class': 'logging.StreamHandler',
121+
'formatter': 'console'
122+
},
123+
},
124+
'loggers': {
125+
'': {
126+
'handlers': ['console'],
127+
'level': level,
128+
'propagate': True,
129+
},
130+
'root': {
131+
'handlers': ['console'],
132+
'level': level,
133+
'propagate': True,
134+
},
135+
}
136+
}
137+
138+
logging.config.dictConfig(LOGGING)
139+
140+
ms = MyMicroservice(path=__file__)
141+
app = ms.create_app()
93142
```
94143

144+
145+
95146
Check more examples in [this Github page](https://github.com/python-microservices/pyms/tree/master/examples)

‎docs/quickstart.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Quickstart
2+
3+
This page gives a good introduction to PyMS. It assumes you already have PyMS installed. If you do not, head over to the [Installation](installation.md) section.
4+
5+
You need to create 2 files: main.py and config.yml:
6+
7+
main.py
8+
```python
9+
from flask import jsonify
10+
11+
from pyms.flask.app import Microservice
12+
13+
ms = Microservice(path=__file__) # 1.1
14+
app = ms.create_app() # 2.1
15+
16+
17+
@app.route("/") # 3.1
18+
def example():
19+
return jsonify({"main": "hello world"})
20+
21+
22+
if __name__ == '__main__':
23+
app.run()
24+
```
25+
26+
config.yml
27+
```yaml
28+
pyms: # 1.2
29+
requests:
30+
data: {}
31+
ms: # 1.3
32+
DEBUG: true
33+
APP_NAME: business-glossary
34+
APPLICATION_ROOT : ""
35+
SECRET_KEY: "gjr39dkjn344_!67#"
36+
```
37+
38+
## So what did that code do?
39+
40+
1. Create a instance of PyMS Microservice class (#1.1). This initialization inject the configuration defined in the
41+
1.3 block and could be accessed through current_app.config. Then, initialize the service defined in the 1.2 block. See [Services](services.md) for more details.
42+
2. Initialize [Flask](https://flask.palletsprojects.com/en/1.1.x/) instance, [Connexion](https://github.com/zalando/connexion)
43+
if it was defined in the pyms configuration block, create a tracer, add health-check blueprint, initialize libs and set the PyMS Microservice in
44+
`ms` attribute and you can access to it with `current_app.ms`. This steps has their each functions and you can easy override it.
45+
3. `create_app` return the flask instance and you can interact with it as a typical flask app
46+
47+
48+
49+
See [Configuration](configuration.md) and [Examples](examples.md) to continue with this tutorial

‎docs/services.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,9 @@ Extends the Microservice with [Connexion](https://github.com/zalando/connexion)
1212

1313
## Requests
1414
Extend the [requests library](http://docs.python-requests.org/en/master/) with trace headers and parsing JSON objects.
15-
Encapsulate common rest operations between business services propagating trace headers if set up.
15+
Encapsulate common rest operations between business services propagating trace headers if set up.
16+
17+
18+
## How to contrib: create your own service:
19+
20+
TODO

‎examples/mininum_microservice/config.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
11
my-minimal-microservice:
2-
APP_NAME: "Python Microservice"
2+
DEBUG: true
3+
TESTING: false
4+
SWAGGER: true
5+
APP_NAME: business-glossary
6+
APPLICATION_ROOT : ""
7+
SECRET_KEY: "gjr39dkjn344_!67#"

‎mkdocs.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
1-
site_name: My Docs
2-
1+
site_name: PyMS
2+
site_url: https://github.com/python-microservices/pyms
3+
repo_url: https://github.com/python-microservices/pyms
4+
repo_name: GitHub
5+
site_author: Alberto Vara
36
nav:
47
- Home: index.md
58
- Structure: structure.md

0 commit comments

Comments
 (0)