Skip to content

Commit

Permalink
docs: Add multi-lang name overrides page
Browse files Browse the repository at this point in the history
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
  • Loading branch information
vikram-dagger committed May 21, 2024
1 parent 51b4f2a commit 43aac09
Show file tree
Hide file tree
Showing 8 changed files with 116 additions and 99 deletions.
67 changes: 67 additions & 0 deletions docs/current_docs/manuals/developer/name-overrides.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
slug: /manuals/developer/name-overrides
displayed_sidebar: "current"
toc_max_heading_level: 2
title: "Name Overrides"
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Name Overrides

:::important
The information on this page is only applicable to the Python and TypeScript SDKs. Name overrides are not currently supported in the Go SDK.
:::

You can change the name of an exposed field or function to work around a reserved keyword or some other naming conflict, but still be able to expose the desired name in the Dagger API. For example, using `import_` in the language, but `import` in the Dagger API.

<Tabs groupId="language">
<TabItem value="Python">

The [`@dagger.function`][@function] decorator and the
[`dagger.field`][dag-field] descriptor have a `name` argument to provide
an alternative name for the Dagger API. And for function arguments,
[annotate][Annotated] with an additional [`dagger.Arg`][dag-arg] metadata.

Here's an example with a renamed object attribute (and constructor argument),
function and function argument:

```python file=./snippets/name-overrides/main.py
```

</TabItem>
<TabItem value="TypeScript">

Add the name override (alias) as a parameter of the corresponding `@field()` or `@func()` decorators

Here's an example with a renamed object attribute (and constructor argument),
function and function argument:

```typescript file=./snippets/name-overrides/typescript/index.ts
```

</TabItem>
</Tabs>

Confirm with `dagger call --help` that the names were overridden:

```
FUNCTIONS
def Definition
import Import the specified image
ARGUMENTS
--def string Definition (default "latest")
```

Confirm the same for the function argument, with `dagger call import --help`:

```
ARGUMENTS
--from string Image ref (default "alpine")
```

[@function]: https://dagger-io.readthedocs.io/en/latest/module.html#dagger.function
[dag-field]: https://dagger-io.readthedocs.io/en/latest/module.html#dagger.field
[dag-arg]: https://dagger-io.readthedocs.io/en/latest/module.html#dagger.Arg
[Annotated]: https://docs.python.org/3/library/typing.html#typing.Annotated

This file was deleted.

Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
import { dag, Container, object, func, field } from "@dagger.io/dagger"

@object()
class MyModule {
/**
* Definition
*/
@field("def")
def_: string

constructor(
/**
* Definition
*/
def_: string = "latest"
) {
this.def_ = def_
}

/**
* Import the specified image
*/
@func("import")
import_(
/**
* Image ref
*/
@field("from")
from_: string = "alpine"
): Container {
return dag.container().withLabel("definition", this.def_).from(from_)
}
}
26 changes: 0 additions & 26 deletions docs/current_docs/manuals/developer/typescript/406314-aliases.mdx

This file was deleted.

This file was deleted.

12 changes: 12 additions & 0 deletions docs/netlify.toml
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,18 @@
to = "/manuals/developer/runtimes"
status = 301

[[redirects]]
# redirect developer manual TypeScript-specific pages to TypeScript common page
from = "/manuals/developer/typescript/:docid/aliases"
to = "/manuals/developer/name-overrides"
status = 301

[[redirects]]
# redirect developer manual Python-specific pages to Python common page
from = "/manuals/developer/python/:docid/name-overrides"
to = "/manuals/developer/name-overrides"
status = 301

[[redirects]]
# redirect developer manual overview pages
from = "/manuals/developer/overview/:docid/*"
Expand Down
12 changes: 4 additions & 8 deletions docs/sidebars.ts
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,10 @@ module.exports = {
"type": "doc",
"id": "manuals/developer/runtimes"
},
{
"type": "doc",
"id": "manuals/developer/name-overrides"
},
{
"type": "doc",
"id": "manuals/developer/error-handling"
Expand Down Expand Up @@ -415,10 +419,6 @@ module.exports = {
"type": "doc",
"id": "manuals/developer/python/attribute-functions"
},
{
"type": "doc",
"id": "manuals/developer/python/name-overrides"
},
{
"type": "doc",
"id": "manuals/developer/python/module-structure"
Expand Down Expand Up @@ -466,10 +466,6 @@ module.exports = {
"type": "doc",
"id": "manuals/developer/typescript/decorators"
},
{
"type": "doc",
"id": "manuals/developer/typescript/aliases"
},
{
"type": "doc",
"id": "manuals/developer/typescript/visibility"
Expand Down

0 comments on commit 43aac09

Please sign in to comment.