feature request: rename `rust_xlsxwriter` into `excelwriter`

[lucatrv]

Feature Request

The reasons for this feature request were discussed here:

I would suggest to change name into excelwriter, for two reasons. The first one is to reduce library and path name lengths, as suggested by @zjp-CN. The second one, in my opinion even more important, is to make this project much more reachable and to avoid confusion with the other existing *xlsxwriter libraries. I remember the first time I was looking for a library to use in my code, I started my research on crates.io with the excel keyword, before the xlsx keyword. Then, it was quite difficult to orient myself among the *xlsxwriter libraries, and to finally understand that rust_xlsxwriter was the best one. Even nowadays, when I google rust_xlsxwriter docs, the link xlsxwriter - Rust comes before rust_xlsxwriter - Rust, and this is an additional source of confusion. Now I know the difference, but I can imagine new users getting confused among these two Rust libraries, and libxlsxwriter. You now have 88k downloads, it is unfortunate to loose them but soon you will have much more, and I think changing name will help that. It may actually be the last opportunity to think about this. You are now implementing these Serde integration features which will be a game changer. You could freeze the rust_xlsxwriter development at release v0.6.0, and notify that all new features will be implemented in excelwriter. I think this is still possible, and if you need some help in changing name references I could help.

[jmcnamara]

I am tempted to do this. I started to migrate to the excelwriter namespace in August 2002 (just before the first real working version of rust_xlsxwriter) but I balked for two reasons:

1. I wanted to maintain a "xlsxwriter" brand across the Rust, Python and C versions.
2. The library isn't strictly an "Excel writer" since it doesn't handle xls files. That point probably isn't important to most people after 15+ years of Excel using the xlsx format.

I can see now that the "brand" have already been diluted in the Rust domain by the existence of an established crate with the same name so I should have used a new name.

So, anyway, I am in favour of this but there will be some technical difficulties:

1. Should I just park rust_xlsxwriter at v0.60.0 (the current) or have a v0.61.0 release with the updated serialization.
2. Should I still publish rust_xlsxwriter wrappers around excelwriter as suggested here: https://users.rust-lang.org/t/best-practice-to-rename-a-published-crate/66273
3. Should I fork or rename the repo:
   • Renaming maintains the users, issue and stars (which are an indicator of usage for people selecting a library).
   • However, as far as I can see it won't move/rename the https://rustxlsxwriter.github.io which I use for secondary docs, hosting images, and the release notes. The secondary docs has become less important over the last year as I figured out how to include non code modules in the crate to have things like the Tutorial and Cookbook. The rustxlsxwriter.github.io link/name probably isn't very important though.

There will probably be a lot of other unintentional gotchas as well but they could be ironed out over time.

The first one is to reduce library and path name lengths

excelwriter is only 4 letters shorter than rust_xlsxwriter but it looks a lot cleaner.

[jmcnamara]

You now have 88k downloads, it is unfortunate to loose them

This is similar to the GitHub stars, it is an indicator to a passerby that the crate is being used and hence some indicator of quality. But a year from now the numbers will be back at a similar level so I am not so worried.

Just on downloads. Taking a visual averaging of rust_xlsxwriter, xlsxwriter and calamine they have approximately the following daily downloads:

• calamine: 2000 per day.
• xlsxwriter: 900 per day.
• rust_xlsxwriter: 400 per day.

By comparison the Python XlsxWriter module has 400,000 daily downloads (averaged over the last year).

I don't have a point to make about this, it is just some interesting information.

[zjp-CN]

Personally I would prefer the derive macro name xlsxwriter over excelwriter because it clearly says xls is not supported, and the target format you want. I mean we don't really need to migrate crates. I don't mind using #[xlsxwriter] under #[derive(rust_xlsxwriter)], as #[xlsxwriter] won't cause misleading information in this context.

---

Thoughs: proc-macros hinder dependency renaming

Although xlsxwriter is a existing crate/package name, users still can use it locally to refer to rust_xlsxwriter if they want a shorter dependency package name via package field in Cargo.toml:

xlsxwriter = {package = "rust_xlsxwriter", version = "*" }
# or equivalently `cargo add rust_xlsxwriter --rename xlsxwriter`

But with derive feature being complete, this trick is strongly discouraged, since it breaks macro hygiene: proc-macros don't know the crate names, specifically proc-macro defined in rust_xlsxwriter_derive crate needs to know the intermediate crate name rust_xlsxwriter. Anyway, that's a main hindrance for RFC: $crate for proc_macro. The case is simple for decl-macros, because they have the meta-variable $crate, which always expands to the defining crate. Thus the decl-macro can just be defined in rust_xlsxwriter, and dep renaming wouldn't really cause troubles.

[jmcnamara]

Personally I would prefer the derive macro name xlsxwriter over excelwriter

As a compromise how about excel as the attribute path. It is short and ties the attribute to the the derive name ExcelSerialize. It also states the target of the serialization.

Something like this:

    #[derive(ExcelSerialize, Serialize)]
    #[serde(rename_all = "PascalCase")]
    #[excel(header_format = Format::new().set_bold())]
    struct Produce {
        fruit: &'static str,

        #[excel(num_format = "$0.00")]
        cost: f64,

        #[serde(skip)]
        in_stock: bool,
    }

[zjp-CN]

As a compromise how about excel as the attribute path. It is short and ties the attribute to the the derive name ExcelSerialize.

Cool. It's a good idea. I like the ExcelSerialize name which indicates the relation with Serialize. That's the my first impression. Now #[excel] looks pretty neat to has same word width as serde attribute.

I can come up with several other options:

• #[derive(XlsxSerialize)] with #[xlsx]
• #[derive(XlsxSerialize)] with #[xlsxwriter]
• #[derive(XlsxWriter)] with #[xlsxwriter]
• #[derive(XlsxWriter)] with #[xlsx]

Among these, #[derive(ExcelSerialize)] with #[excel] and #[derive(XlsxWriter)] with #[xlsxwriter] are my favorites. I like the latter because it tells the functionality for target format in an implicit way as exactly the crate name does.

I'm lucky not to decide which one to be the final APIs. I'm open to all your thoughs. ❤️

[lucatrv]

At the end I think it depends on what's your plan for the future. If you plan to keep both libxlsxwriter and rust_xlsxwriter active, then maybe keeping a common "xlsx" brand across those libraries would make sense (up to your evaluation of course). My impression however was that once rust_xlsxwriter is completed and stabilized, it would replace libxlsxwriter altogether as a new and improved library. In that case I think you could also consider a name switch. Otherwise you could also compromise to xlsxw, which maintains the meaning and "brand", without being too long.

Once the library name decision is finalized, maybe the trait name and annotation tag should be aligned. In case of excelwriter, then ExcelSerialize and excel IMHO would be good choices. Instead in case of rust_xlsxwriter or xlsxw, then actually my preference would be for XlsxSerialize and xlsx. As a trait name, I prefer XlsxSerialize to XlsxWriter because it is more specific to its function, maybe in future you will need to implement other traits within this crate for other functions.

These of course are just my 2 cents, I'm also happy not to have to decide... but you can be certain that this library will be great anyway!

[jmcnamara]

Thanks for the input folks. I'm going to go with #[derive(XlsxSerialize)] with #[xlsx].

I'll make the changes and start prepping the proc macros for release. It needs to be released separately as a crate and then set as a dependency in rust_xlsxwriter. See the following from cargo publish in the top level of the repo:

rust_xlsxwriter (main)$ cargo publish --dry-run
    Updating crates.io index
error: all dependencies must have a version specified when publishing.
dependency `rust_xlsxwriter_derive` does not specify a version
Note: The published dependency will use the version from crates.io,
the `path` specification will be removed from the dependency declaration.

Once that is done and working I'll start prepping rust_xlsxwriter for release. Probably sometime over the weekend if I can get to it.

[jmcnamara]

I'm going to go with #[derive(XlsxSerialize)] with #[xlsx].

This change has now been made on main.

[jmcnamara]

My impression however was that once rust_xlsxwriter is completed and stabilized, it would replace libxlsxwriter altogether as a new and improved library.

Not exactly. I intend to continue adding to and maintaining the C/Python/Rust/Perl versions.

[jmcnamara]

Folks, I've change my mind again on renaming rust_xlsxwriter. I don't think it is worth the effort. I think the rust_xlsxwriter name will eventually stick and at some point in the future it will reach a critical mass of users and people will understand the difference and point it out to other people.

I am one month short of 10 years maintaining the Python version (released February 17 2013) and that eventually reached critical mass as well. At some point in time people started asking xlsxwriter tagged questions on Stack Overflow and some time after that people other than me started answering them. That was a real milestone. Fingers crossed that will happen with the Rust version one day too.

Closing as won't fix.