Skip to content

Commit a4aaf61

Browse files
thomasp85thomasp85
committed
update readme
1 parent 154fb8c commit a4aaf61

File tree

3 files changed

+346
-5
lines changed

3 files changed

+346
-5
lines changed

‎.github/CODE_OF_CONDUCT.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at [email protected].
63+
All complaints will be reviewed and investigated promptly and fairly.
64+
65+
All community leaders are obligated to respect the privacy and security of the
66+
reporter of any incident.
67+
68+
## Enforcement Guidelines
69+
70+
Community leaders will follow these Community Impact Guidelines in determining
71+
the consequences for any action they deem in violation of this Code of Conduct:
72+
73+
### 1. Correction
74+
75+
**Community Impact**: Use of inappropriate language or other behavior deemed
76+
unprofessional or unwelcome in the community.
77+
78+
**Consequence**: A private, written warning from community leaders, providing
79+
clarity around the nature of the violation and an explanation of why the
80+
behavior was inappropriate. A public apology may be requested.
81+
82+
### 2. Warning
83+
84+
**Community Impact**: A violation through a single incident or series of
85+
actions.
86+
87+
**Consequence**: A warning with consequences for continued behavior. No
88+
interaction with the people involved, including unsolicited interaction with
89+
those enforcing the Code of Conduct, for a specified period of time. This
90+
includes avoiding interactions in community spaces as well as external channels
91+
like social media. Violating these terms may lead to a temporary or permanent
92+
ban.
93+
94+
### 3. Temporary Ban
95+
96+
**Community Impact**: A serious violation of community standards, including
97+
sustained inappropriate behavior.
98+
99+
**Consequence**: A temporary ban from any sort of interaction or public
100+
communication with the community for a specified period of time. No public or
101+
private interaction with the people involved, including unsolicited interaction
102+
with those enforcing the Code of Conduct, is allowed during this period.
103+
Violating these terms may lead to a permanent ban.
104+
105+
### 4. Permanent Ban
106+
107+
**Community Impact**: Demonstrating a pattern of violation of community
108+
standards, including sustained inappropriate behavior, harassment of an
109+
individual, or aggression toward or disparagement of classes of individuals.
110+
111+
**Consequence**: A permanent ban from any sort of public interaction within the
112+
community.
113+
114+
## Attribution
115+
116+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
117+
version 2.1, available at
118+
<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
119+
120+
Community Impact Guidelines were inspired by
121+
[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion].
122+
123+
For answers to common questions about this code of conduct, see the FAQ at
124+
<https://www.contributor-covenant.org/faq>. Translations are available at <https://www.contributor-covenant.org/translations>.
125+
126+
[homepage]: https://www.contributor-covenant.org

‎README.Rmd‎

Lines changed: 108 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,5 +20,111 @@ knitr::opts_chunk$set(
2020
[![Codecov test coverage](https://codecov.io/gh/posit-dev/plumber2/graph/badge.svg)](https://app.codecov.io/gh/posit-dev/plumber2)
2121
<!-- badges: end -->
2222

23-
This is a complete rewrite of plumber intended to not be API-compatible with the
24-
old version, but to be recognizable and familiar to long-time plumber users
23+
This is a complete rewrite of [plumber](https://www.rplumber.io). The purpose of
24+
the rewrite is to take everything we've learned from plumber, shed the bad
25+
decision that you inevitably make over the course of development, and start from
26+
scratch.
27+
28+
You'll find that plumber2 is very similar to plumber in a lot of ways, but
29+
diverts in key areas, resulting in API incompitability between the two packages.
30+
Because of this you may need to update your plumber APIs if switching to
31+
plumber2.
32+
33+
## Installation
34+
35+
plumber2 is still a work in progress, and it is recommended to only use it to
36+
experiment and get familiarity with the future direction of plumber APIs. If you
37+
wish to try it out you can install the development version from GitHub using
38+
[pak](https://pak.r-lib.org):
39+
40+
```r
41+
pak::pak("posit-dev/plumber2")
42+
```
43+
44+
## Feedback
45+
46+
At this point in the development feedback is crucial. If you do decide to try
47+
out plumber2, please share your experience, both good and bad, and ask question
48+
as it informs us about where to spend more time with documentation.
49+
50+
## Hello World
51+
52+
Below is a simply "hello world" API written for plumber2 that illustrates some
53+
of the differences from plumber:
54+
55+
```r
56+
#* Echo the parameter that was sent in
57+
#*
58+
#* @get /echo/<msg>
59+
#*
60+
#* @param msg:string The message to echo back.
61+
#*
62+
#* @response 200:{msg:string} A string containing the input message
63+
#*
64+
function(msg) {
65+
list(
66+
msg = paste0("The message is: '", msg, "'")
67+
)
68+
}
69+
70+
#* Plot out data from the iris dataset
71+
#*
72+
#* @get /plot
73+
#*
74+
#* @query spec:enum|setosa, versicolor, virginica| If provided, filter the
75+
#* data to only this species
76+
#*
77+
#* @serializer png{width = 700, height = 500}
78+
#* @serializer jpeg{width = 700, height = 500}
79+
#*
80+
#* @async
81+
function(query) {
82+
myData <- iris
83+
title <- "All Species"
84+
85+
# Filter if the species was specified
86+
if (!is.null(query$spec)){
87+
title <- paste0("Only the '", query$spec, "' Species")
88+
myData <- subset(iris, Species == query$spec)
89+
if (nrow(myData) == 0) {
90+
abort_internal_error("Missing data for {query$spec}")
91+
}
92+
}
93+
94+
plot(
95+
myData$Sepal.Length,
96+
myData$Petal.Length,
97+
main=title,
98+
xlab="Sepal Length",
99+
ylab="Petal Length"
100+
)
101+
}
102+
```
103+
104+
Above you can both see some breaking changes and some new features in action.
105+
The biggest breaking change is that parameters coming from the path, the query
106+
string, and the body are now clearly separated. Only parameters from the path
107+
are provided as direct arguments to the handler function. Query and body
108+
parameters are accessible through the `query` and `body` argument respectively.
109+
As can be seen above they also use different tags in the documentation.
110+
111+
Speaking of documentation, the parsing of plumber blocks have been greatly
112+
improved. It is now build upon roxygen2, so it follows that convention, allowing
113+
multiline tags and defaulting to the first line as title and proceeding untagged
114+
lines as description. The ability to define input and output types has also been
115+
greatly expanded, adding the ability to define nested objects, adding default
116+
values and (as seen above) define enum (factors) to name a few. All input will
117+
get type checked and default value imputed if missing.
118+
119+
For the `/plot` handler you can also see that it specifies multiple serializers.
120+
Doing so will allow the client to request it's prefered response format using
121+
the `Accept` header. Plumber2 will then perform content negotiation to figure
122+
out the best response format based on what it supports and what the client
123+
prefers.
124+
125+
Lastly, you can see a new tag (one of many) in the `/plot` handler. `@async`
126+
allows you to convert your handler into an async handler automatically. It is
127+
still possible to create an async handler manually by returning a promise, but
128+
the new tag significantly simplifies this for the most classic cases. There is
129+
still overhead involved in handling requests asynchronously so this is mainly a
130+
good idea for longer running handlers, but it is shown here as an example.

‎README.md‎

Lines changed: 112 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,115 @@
1010
coverage](https://codecov.io/gh/posit-dev/plumber2/graph/badge.svg)](https://app.codecov.io/gh/posit-dev/plumber2)
1111
<!-- badges: end -->
1212

13-
This is a complete rewrite of plumber intended to not be API-compatible
14-
with the old version, but to be recognizable and familiar to long-time
15-
plumber users
13+
This is a complete rewrite of [plumber](https://www.rplumber.io). The
14+
purpose of the rewrite is to take everything we’ve learned from plumber,
15+
shed the bad decision that you inevitably make over the course of
16+
development, and start from scratch.
17+
18+
You’ll find that plumber2 is very similar to plumber in a lot of ways,
19+
but diverts in key areas, resulting in API incompitability between the
20+
two packages. Because of this you may need to update your plumber APIs
21+
if switching to plumber2.
22+
23+
## Installation
24+
25+
plumber2 is still a work in progress, and it is recommended to only use
26+
it to experiment and get familiarity with the future direction of
27+
plumber APIs. If you wish to try it out you can install the development
28+
version from GitHub using [pak](https://pak.r-lib.org):
29+
30+
``` r
31+
pak::pak("posit-dev/plumber2")
32+
```
33+
34+
## Feedback
35+
36+
At this point in the development feedback is crucial. If you do decide
37+
to try out plumber2, please share your experience, both good and bad,
38+
and ask question as it informs us about where to spend more time with
39+
documentation.
40+
41+
## Hello World
42+
43+
Below is a simply “hello world” API written for plumber2 that
44+
illustrates some of the differences from plumber:
45+
46+
``` r
47+
#* Echo the parameter that was sent in
48+
#*
49+
#* @get /echo/<msg>
50+
#*
51+
#* @param msg:string The message to echo back.
52+
#*
53+
#* @response 200:{msg:string} A string containing the input message
54+
#*
55+
function(msg) {
56+
list(
57+
msg = paste0("The message is: '", msg, "'")
58+
)
59+
}
60+
61+
#* Plot out data from the iris dataset
62+
#*
63+
#* @get /plot
64+
#*
65+
#* @query spec:enum|setosa, versicolor, virginica| If provided, filter the
66+
#* data to only this species
67+
#*
68+
#* @serializer png{width = 700, height = 500}
69+
#* @serializer jpeg{width = 700, height = 500}
70+
#*
71+
#* @async
72+
function(query) {
73+
myData <- iris
74+
title <- "All Species"
75+
76+
# Filter if the species was specified
77+
if (!is.null(query$spec)){
78+
title <- paste0("Only the '", query$spec, "' Species")
79+
myData <- subset(iris, Species == query$spec)
80+
if (nrow(myData) == 0) {
81+
abort_internal_error("Missing data for {query$spec}")
82+
}
83+
}
84+
85+
plot(
86+
myData$Sepal.Length,
87+
myData$Petal.Length,
88+
main=title,
89+
xlab="Sepal Length",
90+
ylab="Petal Length"
91+
)
92+
}
93+
```
94+
95+
Above you can both see some breaking changes and some new features in
96+
action. The biggest breaking change is that parameters coming from the
97+
path, the query string, and the body are now clearly separated. Only
98+
parameters from the path are provided as direct arguments to the handler
99+
function. Query and body parameters are accessible through the `query`
100+
and `body` argument respectively. As can be seen above they also use
101+
different tags in the documentation.
102+
103+
Speaking of documentation, the parsing of plumber blocks have been
104+
greatly improved. It is now build upon roxygen2, so it follows that
105+
convention, allowing multiline tags and defaulting to the first line as
106+
title and proceeding untagged lines as description. The ability to
107+
define input and output types has also been greatly expanded, adding the
108+
ability to define nested objects, adding default values and (as seen
109+
above) define enum (factors) to name a few. All input will get type
110+
checked and default value imputed if missing.
111+
112+
For the `/plot` handler you can also see that it specifies multiple
113+
serializers. Doing so will allow the client to request it’s prefered
114+
response format using the `Accept` header. Plumber2 will then perform
115+
content negotiation to figure out the best response format based on what
116+
it supports and what the client prefers.
117+
118+
Lastly, you can see a new tag (one of many) in the `/plot` handler.
119+
`@async` allows you to convert your handler into an async handler
120+
automatically. It is still possible to create an async handler manually
121+
by returning a promise, but the new tag significantly simplifies this
122+
for the most classic cases. There is still overhead involved in handling
123+
requests asynchronously so this is mainly a good idea for longer running
124+
handlers, but it is shown here as an example.

0 commit comments

Comments
 (0)