# std-uritemplate
[](https://github.com/std-uritemplate/std-uritemplate/blob/main/LICENSE)
[](https://github.com/std-uritemplate/std-uritemplate/blob/main/.github/workflows/test.yml)
[](https://github.com/std-uritemplate/std-uritemplate/tags)
[](https://central.sonatype.com/artifact/io.github.std-uritemplate/std-uritemplate)
[](https://www.npmjs.com/package/@std-uritemplate/std-uritemplate)
[](https://pkg.go.dev/github.com/std-uritemplate/std-uritemplate/go)
[](https://pypi.python.org/pypi/std-uritemplate)
[](https://www.nuget.org/packages/Std.UriTemplate/)
[](https://badge.fury.io/rb/stduritemplate)
[](https://packagist.org/packages/stduritemplate/stduritemplate)
[](https://pub.dev/packages/std_uritemplate)
[](https://github.com/std-uritemplate/std-uritemplate/blob/main/Contributing.md)
This is a complete and maintained cross-language implementation of the [Uri Template specification RFC 6570](https://github.com/uri-templates/uritemplate-spec) Level 4.
> [!NOTE]
> Low activity is this repository is **expected** as long as there are no outstanding bug reports the implementations are considered **stable** and **mature**.
## Available implementations
| Language | Complete | Reviewed | Published |
|---|---|---|---|
| Java | ✅ | ✅ | ✅ |
| Python | ✅ | ❌ | ✅ |
| Typescript | ✅ | ✅ | ✅ |
| Go | ✅ | ✅ | ✅ |
| C# | ✅ | ✅ | ✅ |
| Ruby | ✅ | ❌ | ✅ |
| PHP | ✅ | ✅ | ✅ |
| Swift | ✅ | ❌ | ✅ |
| Dart | ✅ | ✅ | ✅ |
## Usage
### Java
You can use the library as a Maven dependency:
```xml
<dependency>
<groupId>io.github.std-uritemplate</groupId>
<artifactId>std-uritemplate</artifactId>
<version>REPLACE-ME</version>
</dependency>
```
in Gradle:
```groovy
implementation 'io.github.std-uritemplate:std-uritemplate:REPLACE-ME'
```
and use it in your project:
```java
import io.github.stduritemplate.StdUriTemplate;
...
StdUriTemplate.expand(template, substitutions);
```
### Python
Install the package with `pip` (or any alternative):
```bash
pip install std-uritemplate
```
Use the library in your project:
```python
from stduritemplate import StdUriTemplate
...
StdUriTemplate.expand(template, substitutions)
```
### Typescript/Javascript
Install the package using `npm`:
```bash
npm i @std-uritemplate/std-uritemplate
```
Use the package:
```js
const { StdUriTemplate } = require('@std-uritemplate/std-uritemplate');
...
StdUriTemplate.expand(template, substitutions);
```
### Go
Install the package:
```bash
go get github.com/std-uritemplate/std-uritemplate/go
```
and use it:
```go
import stduritemplate "github.com/std-uritemplate/std-uritemplate/go"
...
stduritemplate.Expand(template, substitutions)
```
### C#
Install the package:
```bash
dotnet add package Std.UriTemplate
```
and use it:
```csharp
Std.UriTemplate.Expand(template, substitutions);
```
### Ruby
Install the package:
```bash
gem install stduritemplate
```
and use it:
```ruby
require 'stduritemplate'
...
StdUriTemplate.expand(template, substitutions)
```
### PHP
<!-- Tested following this guide: https://blog.damirmiladinov.com/php/building-and-distributing-a-command-line-php-application.html -->
Install the package:
```bash
composer require stduritemplate/stduritemplate
```
and use it:
```php
use StdUriTemplate\StdUriTemplate;
...
StdUriTemplate::expand($template, $substitutions);
```
### Swift
Install the package, adding to `Package.swift`:
```swift
let package = Package(
...
dependencies: [
...
.package(
url: "https://github.com/std-uritemplate/std-uritemplate-swift.git",
from: "<version>"
)
],
targets: [
.executableTarget(
...
dependencies: [
...
.product(name: "stduritemplate",
package: "std-uritemplate-swift")
]
...
),
]
)
```
and use it:
```swift
import stduritemplate
...
StdUriTemplate.expand(template, substitutions: substs)
```
### Dart
Install the package:
```bash
dart pub add std_uritemplate
```
for flutter:
```bash
flutter pub add std_uritemplate
```
and use it:
```dart
import 'package:std_uritemplate/std_uritemplate.dart';
...
print(StdUriTemplate.expand(template, substitutions));
```
## Design decisions
We have a set of design decisions to guide:
- zero dependencies
- no usage of regexp
- no options/configurations
- only single expansion will be supported
- single method public API
- no language idiomatic API, only 1 low level primitive - we do encourage language-specific wrapper/alternative libraries
- portable implementation across languages based on widely available patterns
- target Level support is 4 (should pass all the canonical tests)
- favor maintenance and readability
- performance until they compromise readability
- one implementation per ecosystem/runtime (e.g. 1 implementation in Java and no Kotlin/Scala/Closure, 1 in TS that will serve JS as well etc.)
- substitutions will be performed only for primitive types
## API
The public API is composed by a single method(in Java for simplicity):
```java
String expand(String template, Map<String, Object> substitutions)
```
all the rest, should not be directly accessible.
## Motivation
[<img alt="alt_text" src="https://imgs.xkcd.com/comics/dependency.png" />](https://xkcd.com/2347/)
In the Kiota project they are using Uri Templates to build URLs, and we have already spent enough life-time dealing with:
- unmaintained projects
- scarce feedback from maintainers
- long release cycles
- different nuances in different implementations
- quirks and integration issues
- frameworks and additional dependencies
- diamond transitive dependencies
We aim to do it differently, by reducing maintenance to a minimum by automating it, and sharing responsibilities to reduce the [bus/truck factor](https://en.wikipedia.org/wiki/Bus_factor#):
- single repository
- multiple implementations
- fully automated testing standardized
- fully automated releases on tag
- same tradeoffs across languages
- familiar implementation across languages
- multiple maintainers in an independent organization
Uri Template is(likely) going to be included in the next OpenAPI specification and we need to rely on a (more) solid foundation to prevent our selves to spend long, tedious hours and days chasing hidden bugs, verifying compatibilities and waiting for unresponsive maintainers.
Raw data
{
"_id": null,
"home_page": "https://github.com/std-uritemplate/std-uritemplate",
"name": "std-uritemplate",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "std-uritemplate, uritemplate, uritemplates, stduritemplate",
"author": "Andrea Peruffo",
"author_email": "andrea.peruffo1982@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/55/cc/4edf18ba0154c338c6054b2d57e954ef8eda90cdd8d435aaf3dcd7cb9a6a/std_uritemplate-2.0.0.tar.gz",
"platform": null,
"description": "# std-uritemplate\n\n[](https://github.com/std-uritemplate/std-uritemplate/blob/main/LICENSE)\n[](https://github.com/std-uritemplate/std-uritemplate/blob/main/.github/workflows/test.yml)\n[](https://github.com/std-uritemplate/std-uritemplate/tags)\n[](https://central.sonatype.com/artifact/io.github.std-uritemplate/std-uritemplate)\n[](https://www.npmjs.com/package/@std-uritemplate/std-uritemplate)\n[](https://pkg.go.dev/github.com/std-uritemplate/std-uritemplate/go)\n[](https://pypi.python.org/pypi/std-uritemplate)\n[](https://www.nuget.org/packages/Std.UriTemplate/)\n[](https://badge.fury.io/rb/stduritemplate)\n[](https://packagist.org/packages/stduritemplate/stduritemplate)\n[](https://pub.dev/packages/std_uritemplate)\n[](https://github.com/std-uritemplate/std-uritemplate/blob/main/Contributing.md)\n\nThis is a complete and maintained cross-language implementation of the [Uri Template specification RFC 6570](https://github.com/uri-templates/uritemplate-spec) Level 4.\n\n> [!NOTE] \n> Low activity is this repository is **expected** as long as there are no outstanding bug reports the implementations are considered **stable** and **mature**.\n\n## Available implementations\n\n| Language | Complete | Reviewed | Published |\n|---|---|---|---|\n| Java | \u2705 | \u2705 | \u2705 |\n| Python | \u2705 | \u274c | \u2705 |\n| Typescript | \u2705 | \u2705 | \u2705 |\n| Go | \u2705 | \u2705 | \u2705 |\n| C# | \u2705 | \u2705 | \u2705 |\n| Ruby | \u2705 | \u274c | \u2705 |\n| PHP | \u2705 | \u2705 | \u2705 |\n| Swift | \u2705 | \u274c | \u2705 |\n| Dart | \u2705 | \u2705 | \u2705 |\n\n## Usage\n\n### Java\n\nYou can use the library as a Maven dependency:\n\n```xml\n<dependency>\n <groupId>io.github.std-uritemplate</groupId>\n <artifactId>std-uritemplate</artifactId>\n <version>REPLACE-ME</version>\n</dependency>\n```\n\nin Gradle:\n\n```groovy\nimplementation 'io.github.std-uritemplate:std-uritemplate:REPLACE-ME'\n```\n\nand use it in your project:\n\n```java\nimport io.github.stduritemplate.StdUriTemplate;\n\n...\n\nStdUriTemplate.expand(template, substitutions);\n```\n\n### Python\n\nInstall the package with `pip` (or any alternative):\n\n```bash\npip install std-uritemplate\n```\n\nUse the library in your project:\n\n```python\nfrom stduritemplate import StdUriTemplate\n\n...\n\nStdUriTemplate.expand(template, substitutions)\n```\n\n### Typescript/Javascript\n\nInstall the package using `npm`:\n\n```bash\nnpm i @std-uritemplate/std-uritemplate\n```\n\nUse the package:\n\n```js\nconst { StdUriTemplate } = require('@std-uritemplate/std-uritemplate');\n\n...\n\nStdUriTemplate.expand(template, substitutions);\n```\n\n### Go\n\nInstall the package:\n\n```bash\ngo get github.com/std-uritemplate/std-uritemplate/go\n```\n\nand use it:\n\n```go\nimport stduritemplate \"github.com/std-uritemplate/std-uritemplate/go\"\n\n...\n\nstduritemplate.Expand(template, substitutions)\n```\n\n### C#\n\nInstall the package:\n\n```bash\ndotnet add package Std.UriTemplate\n```\n\nand use it:\n\n```csharp\nStd.UriTemplate.Expand(template, substitutions);\n```\n\n### Ruby\n\nInstall the package:\n\n```bash\ngem install stduritemplate\n```\n\nand use it:\n\n```ruby\nrequire 'stduritemplate'\n\n...\n\nStdUriTemplate.expand(template, substitutions)\n```\n\n### PHP\n<!-- Tested following this guide: https://blog.damirmiladinov.com/php/building-and-distributing-a-command-line-php-application.html -->\nInstall the package:\n\n```bash\ncomposer require stduritemplate/stduritemplate\n```\n\nand use it:\n\n```php\nuse StdUriTemplate\\StdUriTemplate;\n\n...\n\nStdUriTemplate::expand($template, $substitutions);\n```\n\n### Swift\n\nInstall the package, adding to `Package.swift`:\n\n```swift\nlet package = Package(\n ...\n dependencies: [\n ...\n .package(\n url: \"https://github.com/std-uritemplate/std-uritemplate-swift.git\", \n from: \"<version>\"\n )\n ],\n targets: [\n .executableTarget(\n ...\n dependencies: [\n ...\n .product(name: \"stduritemplate\",\n package: \"std-uritemplate-swift\")\n ]\n ...\n ),\n ]\n)\n```\n\nand use it:\n\n```swift\nimport stduritemplate\n\n...\n\nStdUriTemplate.expand(template, substitutions: substs)\n```\n\n### Dart\n\nInstall the package:\n\n```bash\ndart pub add std_uritemplate\n```\n\nfor flutter:\n\n```bash\nflutter pub add std_uritemplate\n```\n\nand use it:\n\n```dart\nimport 'package:std_uritemplate/std_uritemplate.dart';\n\n...\n\nprint(StdUriTemplate.expand(template, substitutions));\n```\n\n## Design decisions\n\nWe have a set of design decisions to guide:\n\n- zero dependencies\n- no usage of regexp\n- no options/configurations\n- only single expansion will be supported\n- single method public API\n- no language idiomatic API, only 1 low level primitive - we do encourage language-specific wrapper/alternative libraries\n- portable implementation across languages based on widely available patterns\n- target Level support is 4 (should pass all the canonical tests)\n- favor maintenance and readability\n- performance until they compromise readability\n- one implementation per ecosystem/runtime (e.g. 1 implementation in Java and no Kotlin/Scala/Closure, 1 in TS that will serve JS as well etc.)\n- substitutions will be performed only for primitive types\n\n## API\n\nThe public API is composed by a single method(in Java for simplicity):\n\n```java\nString expand(String template, Map<String, Object> substitutions)\n```\n\nall the rest, should not be directly accessible.\n\n## Motivation\n\n[<img alt=\"alt_text\" src=\"https://imgs.xkcd.com/comics/dependency.png\" />](https://xkcd.com/2347/)\n\nIn the Kiota project they are using Uri Templates to build URLs, and we have already spent enough life-time dealing with:\n\n- unmaintained projects\n- scarce feedback from maintainers\n- long release cycles\n- different nuances in different implementations\n- quirks and integration issues\n- frameworks and additional dependencies\n- diamond transitive dependencies\n\nWe aim to do it differently, by reducing maintenance to a minimum by automating it, and sharing responsibilities to reduce the [bus/truck factor](https://en.wikipedia.org/wiki/Bus_factor#):\n\n- single repository\n- multiple implementations\n- fully automated testing standardized\n- fully automated releases on tag\n- same tradeoffs across languages\n- familiar implementation across languages\n- multiple maintainers in an independent organization\n\nUri Template is(likely) going to be included in the next OpenAPI specification and we need to rely on a (more) solid foundation to prevent our selves to spend long, tedious hours and days chasing hidden bugs, verifying compatibilities and waiting for unresponsive maintainers.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "std-uritemplate implementation for Python",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/std-uritemplate/std-uritemplate",
"Repository": "https://github.com/std-uritemplate/std-uritemplate"
},
"split_keywords": [
"std-uritemplate",
" uritemplate",
" uritemplates",
" stduritemplate"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "44991fbcd802c2795325ed49a495b23f4b80ff3543106b31532a114807d27088",
"md5": "100a2a8bb53f40a9de187f9a08e4dfaf",
"sha256": "b69a80b707b93095075066005155eebd9172ec1ac7601992e2f9e4ec380f5a7b"
},
"downloads": -1,
"filename": "std_uritemplate-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "100a2a8bb53f40a9de187f9a08e4dfaf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 6499,
"upload_time": "2024-09-30T08:38:17",
"upload_time_iso_8601": "2024-09-30T08:38:17.826800Z",
"url": "https://files.pythonhosted.org/packages/44/99/1fbcd802c2795325ed49a495b23f4b80ff3543106b31532a114807d27088/std_uritemplate-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "55cc4edf18ba0154c338c6054b2d57e954ef8eda90cdd8d435aaf3dcd7cb9a6a",
"md5": "f94d9379ea30ebce078508ea03d24523",
"sha256": "be88c8a4a89fee6768237f594c537d9347d96d7e68b8ad12200a3f11a0f6398f"
},
"downloads": -1,
"filename": "std_uritemplate-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "f94d9379ea30ebce078508ea03d24523",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 6143,
"upload_time": "2024-09-30T08:38:19",
"upload_time_iso_8601": "2024-09-30T08:38:19.604475Z",
"url": "https://files.pythonhosted.org/packages/55/cc/4edf18ba0154c338c6054b2d57e954ef8eda90cdd8d435aaf3dcd7cb9a6a/std_uritemplate-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 08:38:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "std-uritemplate",
"github_project": "std-uritemplate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "std-uritemplate"
}
JSON
