What is the difference between SortField and EncodingSortField?

What is the difference between SortField and EncodingSortField? I am interested in sorting the markers of an axis, and I often see these two coming up in examples and discussions (example for EncodingSortField, example for SortField).

I don't know how to parse the doc string for EncodingSortField:

A sort definition for sorting a discrete scale in an encoding field definition.

Compare with the doc string for SortField:

A sort definition for transform

Can you explain the difference between these two things? When should I choose to use EncodingSortField instead of SortField?

Although their names are similar, they have very different purposes and uses.

SortField is used to sort the underlying data within transformations like aggregations, window operations, etc., before visualising it. For example:

import altair as alt
import pandas as pd

data = pd.DataFrame({
    'date': ['2021-01-01', '2021-01-02', '2021-01-03'],
    'sales': [30, 20, 50]
})

chart = alt.Chart(data).transform_window(
    sort=[alt.SortField('date')],
    cumulative_sales='sum(sales)',
    frame=[None, 0]
).mark_line().encode(
    x='date:T',
    y='cumulative_sales:Q'
)

chart

EncodingSortField sorts the presentation/encoding of the data on the chart axis as it is visualised. For example:

import altair as alt
import pandas as pd

data = pd.DataFrame({
    'category': ['A', 'B', 'C'],
    'value': [3, 1, 2]
})

chart = alt.Chart(data).mark_bar().encode(
    x=alt.X('category', sort=alt.EncodingSortField(field='value', order='ascending')),
    y='value'
)

chart